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:

{
  "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.

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:

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

Representative request:

Paginated request

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"

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

Understand point-in-time retrieval, restatements, and deterministic datasets.

Data model

Learn how companies, filings and statements relate.

Versioning

Work with latest, version history, and as_of semantics without historical drift.