Pagination & filtering

Every list endpoint in the QuantConomy API returns the same envelope: a data array plus a meta block that describes the page. High-churn feeds use cursor-based pagination, reference/catalog endpoints use page metadata, and account/billing logs use offset metadata.

This guide uses GET /api/v1/entries as the worked cursor example. The same data + meta contract applies to every list endpoint (assets, markets, publishers, clusters, SEC datasets, prediction markets, request logs, billing history, and so on).

The response envelope

A successful list response looks like this:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Apple Reports Record Q4 Earnings, Beats Expectations",
      "excerpt": "Apple Inc. reported quarterly earnings that exceeded analyst expectations...",
      "url": "https://reuters.com/technology/apple-q4-earnings-2024",
      "urlDomain": "reuters.com",
      "author": "John Smith",
      "imageUrl": "https://example.com/images/apple-earnings.jpg",
      "language": "en",
      "sentimentScore": 0.75,
      "assetKeys": ["us_stock_AAPL"],
      "topicSlugs": ["earnings-reports", "technology"],
      "publishedAt": "2024-01-15T14:30:00.000Z",
      "createdAt": "2024-01-15T14:35:00.000Z"
    }
  ],
  "meta": {
    "totalCount": 50000,
    "count": 50,
    "limit": 50,
    "hasMore": true,
    "hasPrev": false,
    "nextCursor": "MjAyNC0wMS0xNVQxNDozNTowMC4wMDBaXzU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMA==",
    "prevCursor": null,
    "sort": "createdAt:desc",
    "query": null,
    "plan": "starter"
  }
}

Cursor meta fields

Field	Type	Description
totalCount	number	Total number of records matching your filters across all pages.
count	number	Number of items in this page’s data array.
limit	number	The effective page size that was applied (may be lower than you requested).
hasMore	boolean	true if there are more (older) results after this page.
hasPrev	boolean	true if there are newer results before this page.
nextCursor	string | null	Opaque cursor for the next (older) page. null when hasMore is false.
prevCursor	string | null	Opaque cursor for the previous (newer) page. null when hasPrev is false.
sort	string	The sort order that was applied.
query	string | null	The search term that was applied, if any.
plan	string	Your plan slug (authenticated requests only).

Note

Cursors are opaque, base64-encoded tokens. Don’t try to parse or construct them yourself — always pass back the exact value the API returned.

Page and offset meta fields

Reference/catalog endpoints expose page, prevPage, and nextPage in meta. Account request logs and billing history expose offset navigation:

Field	Type	Description
totalCount	number	Total number of records matching your filters across all pages.
count	number	Number of items in this page’s data array.
limit	number	The effective page size that was applied.
offset	number	Number of records skipped before this page.
hasMore	boolean	true if another page exists after this one.
prevOffset	number | null	Offset for the previous page. null when this is the first page.
nextOffset	number | null	Offset for the next page. null when there are no more results.

For offset lists, pass limit and offset in the query string and use meta.nextOffset / meta.prevOffset to drive your UI.

How cursor pagination works

GET /api/v1/entries is sorted newest-first by default (createdAt:desc), so “forward” means moving toward older entries.

• Omit after and before on the first request to get the newest page.
• To get the next (older) page, pass the response’s nextCursor back as the after query parameter.
• To go back to a newer page, pass prevCursor back as the before parameter.
• Stop when hasMore is false (or nextCursor is null).

Caution

You cannot send after and before in the same request — the API returns a 400 VALIDATION error. Use after to walk toward older items or before to walk toward newer ones, not both.

First page

curl

curl -s "https://api.quantconomy.com/api/v1/entries?limit=50" \
  -H "Authorization: Bearer mtk_your_key_here"

JavaScript

const res = await fetch('https://api.quantconomy.com/api/v1/entries?limit=50', {
  headers: { Authorization: 'Bearer mtk_your_key_here' },
});
const { data, meta } = await res.json();

Next page

Take meta.nextCursor from the previous response and pass it as after:

curl -s "https://api.quantconomy.com/api/v1/entries?limit=50&after=MjAyNC0wMS0xNVQxNDozNTowMC4wMDBaXzU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMA==" \
  -H "Authorization: Bearer mtk_your_key_here"

Paging through every result

Loop until hasMore is false, feeding nextCursor back as after each time.

curl + jq

#!/usr/bin/env bash
KEY="mtk_your_key_here"
BASE="https://api.quantconomy.com/api/v1/entries?limit=100&assetKey=us_stock_AAPL"
after=""

while :; do
  url="$BASE"
  [ -n "$after" ] && url="$BASE&after=$after"

  resp=$(curl -s "$url" -H "Authorization: Bearer $KEY")

  # ...do something with the page here...
  echo "$resp" | jq -r '.data[].title'

  has_more=$(echo "$resp" | jq -r '.meta.hasMore')
  after=$(echo "$resp" | jq -r '.meta.nextCursor')

  [ "$has_more" = "true" ] && [ "$after" != "null" ] || break
done

JavaScript

const KEY = 'mtk_your_key_here';
const base = new URL('https://api.quantconomy.com/api/v1/entries');
base.searchParams.set('limit', '100');
base.searchParams.set('assetKey', 'us_stock_AAPL');

async function fetchAll() {
  const all = [];
  let after = null;

  do {
    const url = new URL(base);
    if (after) url.searchParams.set('after', after);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const { data, meta } = await res.json();

    all.push(...data);
    after = meta.hasMore ? meta.nextCursor : null;
  } while (after);

  return all;
}

const entries = await fetchAll();
console.log(`Fetched ${entries.length} entries`);

Tip

Each page is one billable request. With limit=100 (the authenticated maximum), paging through 50,000 entries costs 500 requests and 500 credits. Use filters to narrow totalCount before you start looping, and respect your plan’s rate limits.

Result caps vs limit

A key is required on every endpoint. The limit parameter accepts values from 1 to 100, but the effective page size depends on your access level. For your own key the API silently clamps limit down to your plan’s cap — meta.limit always reports the value that was actually applied.

Caller	Default limit	Max limit	Pagination	Advanced filters
Demo key (mtk_demo)	3	3	Not available	Not available
Your own key (any plan)	50	100	Cursor pagination	Available

The demo key behaves differently: instead of silently clamping, it rejects ?limit greater than 3 with 400 BAD_REQUEST, and it rejects any pagination parameter (cursor, offset, page) with 400 as well — it can only ever return the first 3 results. To raise the cap, paginate, and unlock the advanced filters below, create your own key.

Note

Cursor pagination works for any of your own keys; only the demo key cannot paginate. Every request (including the demo key’s) spends credits — the demo key draws from a shared hourly budget.

Filtering

Pass filters as query parameters. They combine with AND semantics and apply to totalCount as well as the returned page.

Available to everyone

Parameter	Description
search	Full-text search across the title and content.
limit	Page size, 1–100 (clamped to your cap).

Own-key-only filters

These are ignored for demo-key requests:

Parameter	Description	Example
hasAssets	true to only return entries that mention a financial asset.	hasAssets=true
assetKey	Filter by mentioned asset key.	assetKey=us_stock_AAPL
assetId	Filter by asset UUID.	assetId=<uuid>
topicSlug	Filter by topic slug.	topicSlug=interest-rates
topicId	Filter by topic UUID.	topicId=<uuid>
publisherSlug	Filter by publisher slug.	publisherSlug=reuters
publisherId	Filter by publisher UUID.	publisherId=<uuid>
language	Filter by detected language code.	language=en
countryCode	Filter by publisher country code.	countryCode=US
sentimentScoreMin	Minimum sentiment score, −1 to 1.	sentimentScoreMin=0.2
sentimentScoreMax	Maximum sentiment score, −1 to 1.	sentimentScoreMax=0.9
publishedAfter	Only entries published after this ISO 8601 timestamp.	publishedAfter=2024-01-01T00:00:00.000Z
publishedBefore	Only entries published before this ISO 8601 timestamp.	publishedBefore=2024-12-31T23:59:59.999Z

Example: bullish Apple-related news from US publishers, published in 2024:

curl -s "https://api.quantconomy.com/api/v1/entries?\
assetKey=us_stock_AAPL&\
countryCode=US&\
sentimentScoreMin=0.3&\
publishedAfter=2024-01-01T00:00:00.000Z&\
limit=100" \
  -H "Authorization: Bearer mtk_your_key_here"

Tip

search does a keyword/full-text match. To find entries by meaning rather than exact terms, use Semantic search instead.

Sorting

Use sortBy to control the order. The default is createdAt:desc.

Value	Order
createdAt:desc	Recently added first (default).
createdAt:asc	Earliest added first.
publishedAt:desc	Newest by publication date.
publishedAt:asc	Oldest by publication date.

curl -s "https://api.quantconomy.com/api/v1/entries?sortBy=publishedAt:desc&limit=50" \
  -H "Authorization: Bearer mtk_your_key_here"

Caution

Keep sortBy constant while paginating a result set. Cursors are tied to the sort order they were generated under; switching sortBy mid-walk invalidates the cursor sequence.

Recap

1. Request the first page with no cursor and your desired limit, filters, and sortBy.

2. Read meta.hasMore and meta.nextCursor from the response.

3. While hasMore is true, request the next page with after=<nextCursor>.

4. Stop when hasMore is false.

Related

• Semantic search — meaning-based search over entries.
• Authentication — raise your result cap and unlock filters.
• Rate limits — request budgets per plan.
• Entries API reference