Skip to main content
The API uses three pagination conventions, depending on the route family. Most dataset routes are cursor-based; the SEC data routes are limit-only and newest-first; one document route uses limit + offset. This page tells you which is which.

​
Cursor-based (most dataset routes)

The company registry, screening, news, events, guidance, market data, benchmarks, regional datasets, directories, and Form 20-F routes all share one response shape:
The rules:
  1. Request the first page with your filters and an optional limit.
  2. If next_cursor is a string, there are more rows: request the same URL again with ?cursor=<next_cursor>, passing the value back verbatim — it is opaque, and its format varies by route.
  3. next_cursor: null means you are on the last page.
Do not build, edit, or store-and-truncate cursor values. A cursor that does not match what the API handed you is rejected with a hard 400 — "Malformed cursor. Pass back next_cursor unchanged." The API never silently restarts a paging sequence from the beginning.
Cursors encode a position, not a snapshot — if rows are inserted while you page, a long-running sweep sees the dataset as it changes.

​
Limit caps by route

The caps below apply whichever pagination style the route uses — including the limit+offset route GET /v1/documents/by-ticker/:ticker. limit defaults vary, and each route caps it: A limit above the cap is a validation error, not a silent clamp.

​
Limit-only, newest-first (SEC data routes)

The SEC data routes — /v1/filings, /v1/financials*, /v1/financial-metrics, /v1/company/facts, /v1/institutional-holdings, /v1/insider-trades — have no cursor at all. They return the newest rows first, up to limit: To reach further back than one page, narrow the window with the date filters instead of paging: filed_at_lte on filings, report_period_lte on financials and holdings. Each narrowed request is a fresh query, so walking backwards through time is filter-by-date, not cursor-following:
This convention matches the financialdatasets.ai API, so SDKs and scripts written against it work unchanged. See Errors for the other compatibility behaviors these routes share.

​
Limit + offset (one route)

Exactly one route pages by offset: GET /v1/documents/by-ticker/:ticker takes limit (1–100, default 20) and offset (default 0), and its meta object reports total so you know when to stop:

​
Choosing a page size

Every request costs one credit regardless of how many rows it returns, so larger pages are cheaper: sweeping 10,000 companies at limit=1000 costs 10 credits; the same sweep at the default limit costs far more. Use the largest limit the route allows unless response size is a constraint on your side.

Errors

The malformed-cursor 400 and the rest of the status-code table.

Plans and credits

Why page size matters: one call is one credit, whatever the page holds.