Skip to main content
Use the connection setup. 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:
The response contains filings and a nullable nextCursor. When the cursor is non-null, pass it with the same filters and page size:
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. 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: 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. 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.