# Pagination

List endpoints may return paginated results rather than the full dataset in a single response.

## Collection routes

Expect pagination on endpoints that return collections, timelines, or large result sets.

Check the API reference for endpoint-specific parameters and response fields.

## Common parameters

`page` and `page_size` are the standard pair and carry 25 of the paginated
routes. Two variants exist:

- `per_page` is accepted as an alias for `page_size` on the company filings,
  statements and disclosures listings, on `/v1/edgar/restatement-alerts`, and on
  `/v1/bulk/snapshots`.
- `limit` is a row cap rather than a page selector, and appears only on
  `/v1/edgar/reconciliation/ledger` and `/v1/edgar/reconciliation/summary`.

Not every endpoint uses every parameter, so rely on the route contract instead
of assuming one universal shape.

A query parameter a route does not declare is **refused**, not ignored. The
request fails with `400 VALIDATION_ERROR` naming what it did not recognize and
what the route accepts:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "http_status": 400,
    "message": "Unrecognized query parameter(s): fiscal_year. The request was refused rather than answered without them.",
    "details": {
      "unknown_parameters": ["fiscal_year"],
      "accepted_parameters": ["detail", "from_date", "include_restated", "include_usd", "page", "page_size", "per_page", "statement_type", "to_date"]
    },
    "trace_id": "…"
  }
}
```

Read `details.accepted_parameters` — it is the route's actual contract, so a
misspelling or a filter that lives under a different name is answered directly.
`/v1/edgar/companies/{cik}/statements` narrows by `from_date` and `to_date`
rather than by fiscal year, which this makes visible instead of silently
returning the filer's whole history.

> **Note:** Earlier releases dropped an unrecognized parameter and served the request
> without it, so a misspelled filter returned an unfiltered page that looked
> identical to a filter matching everything. If you have a client that sends
> extra parameters, it will now receive `400` rather than a
> quietly wrong answer.

## Response shape

Representative collection payload:

```json
{
  "page": 1,
  "page_size": 50,
  "total": 128,
  "items": []
}
```

Representative request:

**Paginated request**

```bash
curl -X GET "https://api.arche.fi/v1/edgar/restatement-alerts?page=1&page_size=50" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
```

```ts
const response = await fetch(
  'https://api.arche.fi/v1/edgar/restatement-alerts?page=1&page_size=50',
  {
    headers: {
      'X-Api-Key': process.env.ARCHE_API_KEY!,
      Accept: 'application/json',
    },
  },
)
```

```python
response = requests.get(
    "https://api.arche.fi/v1/edgar/restatement-alerts",
    params={"page": 1, "page_size": 50},
    headers={"X-Api-Key": api_key, "Accept": "application/json"},
    timeout=30,
)
```

## Best practices

- Prefer smaller page sizes for interactive tooling.
- Use stable filters and sorting when exporting data across multiple pages.
- Persist the exact query parameters used for reproducible research jobs.
- Avoid parallel page fan-out until you know a route’s ordering guarantees.

## Next steps

- [Concepts](https://docs.arche.fi/concepts): Understand point-in-time retrieval, restatements, and deterministic datasets.
- [Data model](https://docs.arche.fi/data-model): Learn how companies, filings and statements relate.
- [Versioning](https://docs.arche.fi/versioning): Work with latest, version history, and as_of semantics without historical drift.