# Pagination

Lists come in one envelope. Certain routes page with a **keyset cursor** and return no total count. One request returns a full page: `GET /v3/filings` returns 50 rows by default, and up to 1000 with `limit`; each route's reference page gives its own default and maximum. Follow `next_cursor` to go on.

```json
{
  "data": [
    {
      "accession": "…"
    },
    {
      "accession": "…"
    },
    {
      "accession": "…"
    }
  ],
  "has_more": true,
  "next_cursor": "…"
}
```

## Following a cursor

1. Send the request with your filters and no `cursor`.
2. If `has_more` is true, send the same request again with `cursor` set to the `next_cursor` you received.
3. Stop when `has_more` is false.

```bash
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
  'https://api.secblast.com/v3/filings?form=10-K&limit=200'

curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
  'https://api.secblast.com/v3/filings?form=10-K&limit=200&cursor=NEXT_CURSOR_FROM_THE_PREVIOUS_PAGE'
```

In Python, continuing the [quickstart](https://www.secblast.com/docs) session:

```python
params = {"form": "10-K", "filed_from": "2026-09-01", "filed_to": "2026-09-30", "limit": 200}
while True:
    r = session.get(f"{API}/filings", params=params, timeout=30)
    r.raise_for_status()
    page = r.json()
    for filing in page["data"]:
        handle(filing)
    if not page["has_more"]:
        break
    # Same filters, same sort and order; only the cursor changes.
    params["cursor"] = page["next_cursor"]
```

## Rules

- **A cursor is opaque.** Pass back exactly what you received.
- **A cursor belongs to its query.** Use it with the same filters, the same `sort` and the same `order`; change none of them between pages.
- **Trust `has_more`, not the page length.** With `sort=accepted_at` and no `cik`, a page can hold fewer rows than `limit`, even none, and still have more: keep following `next_cursor` until `has_more` is false. Narrow such a query with `accepted_from` and `accepted_to`.
- **Very large filers.** For a company with tens of thousands of filings, `sort=accepted_at` with `order=asc` can return empty pages while `has_more` is true, and `sort=accession` with a `cik` and another filter can take several seconds or end in a `504` with code `timeout`. The default sort, `filing_date`, does not have these limits.
- **A 503 with code `snapshot_unavailable`** on a continuation means the page cannot be produced right now; send the same request again after the `Retry-After` delay. See [Errors](https://www.secblast.com/docs/errors).

## Page size

| Route | limit | Default |
|---|---|---|
| [`GET /v3/callbacks/deliveries`](https://www.secblast.com/docs/reference/get-callbacks-deliveries) | Page size, 1..100. | `20` |
| [`GET /v3/callbacks/endpoints`](https://www.secblast.com/docs/reference/get-callbacks-endpoints) | Page size, 1..100 (GET). | `50` |
| [`GET /v3/companies`](https://www.secblast.com/docs/reference/get-companies) | Page size, 1..1000. | `100` |
| [`GET /v3/companies/{cik}/segments`](https://www.secblast.com/docs/reference/get-companies-cik-segments) | Period ends per page, newest first, 1..200 (default 1: the latest fiscal year). | `1` |
| [`GET /v3/companies/{cik}/standard`](https://www.secblast.com/docs/reference/get-companies-cik-standard) | Period ends per page, newest first, 1..1000. | `8` |
| [`GET /v3/companies/{cik}/statements`](https://www.secblast.com/docs/reference/get-companies-cik-statements) | Reports, 1..8 (1 with a category alone). | `1` |
| [`GET /v3/entities`](https://www.secblast.com/docs/reference/get-entities) | Maximum results, 1..50. | `20` |
| [`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) | Page size, 1..1000. | `50` |
| [`GET /v3/events/8k/{item}`](https://www.secblast.com/docs/reference/get-events-8k-item) | Page size, 1..500. | `50` |
| [`GET /v3/events/items`](https://www.secblast.com/docs/reference/get-events-items) | Page size, 1..1000. | `50` |
| [`GET /v3/filings`](https://www.secblast.com/docs/reference/get-filings) | Page size, 1..1000. | `50` |
| [`GET /v3/filings/{accession}/13f/holdings`](https://www.secblast.com/docs/reference/get-filings-accession-13f-holdings) | Page size, 1..1000. | `200` |
| [`GET /v3/filings/{accession}/facts`](https://www.secblast.com/docs/reference/get-filings-accession-facts) | Page size, 1..5000. | `1000` |
| [`GET /v3/filings/{accession}/nport`](https://www.secblast.com/docs/reference/get-filings-accession-nport) | Holdings per page, 1..5000. | `500` |
| [`GET /v3/filings/{accession}/parsed/changes`](https://www.secblast.com/docs/reference/get-filings-accession-parsed-changes) | Page size, 1..500. | `100` |
| [`GET /v3/filings/{accession}/statements`](https://www.secblast.com/docs/reference/get-filings-accession-statements) | Roles per page, 1..25. | `25` |
| [`GET /v3/filings/{accession}/statements/roles`](https://www.secblast.com/docs/reference/get-filings-accession-statements-roles) | Roles per page, 1..500. | `500` |
| [`GET /v3/filings/{accession}/tables`](https://www.secblast.com/docs/reference/get-filings-accession-tables) | Page size, 1..1000. | `100` |
| [`GET /v3/financials/facts`](https://www.secblast.com/docs/reference/get-financials-facts) | Page size, 1..2000. | `200` |
| [`GET /v3/financials/frames`](https://www.secblast.com/docs/reference/get-financials-frames) | Page size, 1..50000: rows in CIK, unit and dimension order. | `500` |
| [`GET /v3/financials/standard`](https://www.secblast.com/docs/reference/get-financials-standard) | Companies with a value per page, CIK order, 1..10000. | `100` |
| [`GET /v3/funds/holdings`](https://www.secblast.com/docs/reference/get-funds-holdings) | Page size, 1..1000. | `500` |
| [`GET /v3/funds/{series_id}/reports`](https://www.secblast.com/docs/reference/get-funds-series-id-reports) | Page size, 1..1000. | `500` |
| [`GET /v3/offerings`](https://www.secblast.com/docs/reference/get-offerings) | Page size, 1..1000. | `500` |
| [`GET /v3/ownership/insiders/holdings`](https://www.secblast.com/docs/reference/get-ownership-insiders-holdings) | Page size, 1..500. | `100` |
| [`GET /v3/ownership/insiders/transactions`](https://www.secblast.com/docs/reference/get-ownership-insiders-transactions) | Page size, 1..500. | `100` |
| [`GET /v3/ownership/institutional/holders`](https://www.secblast.com/docs/reference/get-ownership-institutional-holders) | Page size, 1..1000. | `200` |
| [`GET /v3/ownership/institutional/managers/{cik}/holdings`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-holdings) | Page size, 1..1000. | `200` |
| [`GET /v3/ownership/institutional/managers/{cik}/periods`](https://www.secblast.com/docs/reference/get-ownership-institutional-managers-cik-periods) | Page size, 1..200. | `50` |
| [`GET /v3/ownership/proposed-sales`](https://www.secblast.com/docs/reference/get-ownership-proposed-sales) | Page size, 1..200. | `50` |
| [`GET /v3/reports`](https://www.secblast.com/docs/reference/get-reports) | Page size, 1..200. | `50` |
| [`GET /v3/search`](https://www.secblast.com/docs/reference/get-search) | Page size, 1 to 100. | `20` |
| [`GET /v3/search/subscriptions`](https://www.secblast.com/docs/reference/get-search-subscriptions) | Page size, 1..100 (GET). | `50` |
| [`GET /v3/sections`](https://www.secblast.com/docs/reference/get-sections) | Page size, 1..1000. | `50` |
| [`GET /v3/stream`](https://www.secblast.com/docs/reference/get-stream) | Events per answer, 1 to 1000. | `100` |

## The one offset-paged list

[`GET /v3/entities/{cik}/filings`](https://www.secblast.com/docs/reference/get-entities-cik-filings) and [`GET /v3/filings/{accession}/items/{code}/text`](https://www.secblast.com/docs/reference/get-filings-accession-items-code-text) and [`GET /v3/filings/{accession}/sections/{section}/text`](https://www.secblast.com/docs/reference/get-filings-accession-sections-section-text) are the SEC's own filing lists for an entity and are paged with `offset`, not a cursor: pass the response's `next_offset` back as `offset` until it is null. Its `next_cursor` is always null. The list can shift when a new snapshot is loaded.

## Other lists

The remaining lists use the same envelope and take no cursor.
