> ## Documentation Index
> Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination and recovery

> Continue research safely, retry lost responses, and recover without changing the meaning of a request.

Use the [connection setup](/guides/index#connect-once). Check HTTP status before
interpreting a response as research data. Failed requests are not empty result
sets, and an empty page is not necessarily the end of a traversal.

## Continue a catalog query

Request the first page with the filters that define your question:

```http theme={null}
GET /api/v2/filings?state=TX&toi=04.0&limit=2
```

The response contains `filings` and a nullable `nextCursor`. When the cursor is
non-null, pass it with the same filters and page size:

```http theme={null}
GET /api/v2/filings?state=TX&toi=04.0&limit=2&cursor={nextCursor}
```

Keep the request parameters and the cursor **used to request** a page until that
page is safely consumed. On a lost response, retry that input cursor. Advance to
the returned `nextCursor` only after storing the result. Do not decode tokens or
compare their strings to decide whether two pages are equal; retries can issue
different continuation tokens. Deduplicate Filing results by `id`.

Continue until `nextCursor` is null. File inventories may return an empty page
with a non-null cursor after an authorization scan. GET catalog pages use live
keysets; they are not a frozen snapshot, and edits can change membership.

## Change the question deliberately

Filing cursors bind their operation, filters, sorting, effective size, and caller
scope. For example, changing the example's state to CA while retaining the Texas
cursor returns `400 invalid_cursor`. To investigate California, keep the new
filters and start without a cursor. Do not append that page to the old Texas
traversal without labeling it as a separate query.

For an expired cursor with an unchanged question, restart that original query
without the cursor. Filing cursors expire 24 hours after the first page; continuing
does not extend the lifetime. Access is checked again on every request.

| Operation | Preserve on continuation | Consistency to expect |
| - | - | - |
| Filing catalog | Filters, sort, limit | Live keysets |
| Filing search | Query, filters, scope, sort, passage setting, limit | Live search reruns; text results cover a bounded window |
| Filing files/forms | Parent Filing ID and limit | Live inventory/schedule; replacement can invalidate or change results |
| File text | File ID and `maxBytes` | One extracted-text revision; restart if the revision changes |
| Carrier/MGA directories | Filters and limit | Existing offset-based pagination; do not assume Filing binding or expiry guarantees |

For POST search, retry the same semantic JSON body with the input `cursor` added
or replaced. A null search cursor exhausts the available window; check `exhaustive`
before making a catalog-coverage claim. For text, use the
[text continuation example](/guides/read-filing-documents#save-a-checkpoint-and-resume):
deduplicate by revision and starting byte offset, and never combine revisions.

## Repair a failed request

API-generated errors contain a stable `code` and human-readable `error`.
Optional `details` locate invalid inputs; optional `requestId` helps trace an
attempt. Use the status and code for control flow, with HTTP status as the fallback
for unknown future codes.

| Response | Action |
| - | - |
| `400 invalid_request` | Check the operation's schema, field names, enum values, and bounds. Correct the request before retrying. |
| `400 invalid_cursor` | Restart the intended traversal without a cursor; keep old results distinct if query or revision changed. |
| `401 unauthenticated` | Check the key and host, then verify `/users/me`. Do not repeatedly retry the same invalid credential. |
| `403 forbidden` or `download_restricted` | Respect the access/export restriction. A discovered ID does not grant content access. |
| `404 not_found` | The documented resource may be missing or inaccessible. Do not infer zero results or absent extraction. |
| `409 text_unavailable` | Existing readable extraction is unavailable; try the original download if permitted. No OCR or extraction was started. |
| `409 inventory_limit_exceeded` | Traversal exceeded a supported bound. Report the limitation; do not treat a partial inventory as complete. |
| `413 request_too_large` / `415 unsupported_media_type` | Reduce the JSON request or use `Content-Type: application/json`. |
| `503 temporarily_unavailable` | Respect `Retry-After`, use bounded retries of the same request, and retain the checkpoint. |
| `500 internal_error` | Retain request context and report a persistent failure; do not infer a successful write or an empty read. |

For example, a `limit` of zero is outside the documented range. A validation
detail may identify `path: ["limit"]`; details can also be omitted. An unknown-field
error may identify only the containing object, with `path: []`, rather than repeat
the unrecognized input. Compare the request with that operation's reference.
Do not silently drop a filter: removing it changes the research question.

## Recognize an environment mismatch

Use docs for the API host you are calling. Canary documentation can describe a
capability before that host finishes deploying it. A successful `/users/me`
confirms credentials, not the availability of every documented route.

If a documented parameter is rejected as unknown, or a known-file read returns
an unexpected non-JSON 404, check the host and exact operation path. Record the
HTTP status, content type, request ID if present, timestamp, and sanitized request
shape. A single controlled retry can help identify a transient response; avoid
an unbounded loop or guessing undocumented endpoints. Resume the blocked workflow
after availability is confirmed, or explicitly describe a supported fallback.

Never store API keys, authorization headers, or signed download URLs in diagnostic
evidence. Report resource IDs and any opaque version/revision needed to reproduce
the problem instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.