Pagination and output
A source API collects records within its validated plan and requested limits. A bounded run is not a promise to enumerate an entire website.
On this page
Set the collection scope#
A run collects until the source has no more records or one of these ends it:
| Bound | Effect |
|---|---|
max_items |
Stops after this many de-duplicated records. Optional; no default. |
timeout_seconds |
Stops after this much running time. Default 10800; queued time does not count. |
| Money | Stops when the workspace's Units or monthly usage budget can pay for no further page. |
Start with a small max_items, then inspect the records and summary. To skip detail reads on a first request, send enrich_records: false (or detail_limit: 0 on APIs created before enrich_records). Different sources may use links, buttons, scrolling, or an underlying API; the accepted definition determines what can be collected.
Bounds are run options, not page numbers or cursors. Do not add page, offset, or cursor inputs unless your generated contract explicitly supports them. Repeating the same run is a new collection attempt, not an instruction to fetch the next page. To read a long run's records as they arrive, follow next_cursor on GET /v1/runs/{run_id}/items.
run.stop_reason says which bound ended the run: source_exhausted, max_items, timeout, budget_exhausted, scope_end, series_unfilled, end_not_confirmed, aborted, blocked, or error. A run returns every record the source holds, or stops at your max_items, your timeout_seconds or your money; it never ends on a page count. end_not_confirmed means the run read only what its definition had proven and nothing showed that the source has no more. error also covers a page read that failed after earlier pages. Records committed before the stop stay readable and charged.
Interpret completeness#
Check summary.within_scope_passed alongside summary.status. A result may be completed within its selected scope, bounded by the chosen limits, or partial because some expected work did not complete.
A successful bounded run can still omit later pages and unselected detail records. Review summary.limits, details_selected, details_complete, and details_not_selected where present. Do not describe the response as the full catalog when catalog_complete is false.
The fictional source-change example shows why returned records must be read together with a partial execution summary.
Use the schema#
Field names and types belong to the accepted source definition. Validate against its schema and distinguish a missing value from an empty string or zero. Detail fields may be unavailable when detail enrichment is disabled or incomplete.
Treat example records as examples of the build, not current data. Executing a versioned definition applies its rules to source content available at run time; pinning the version does not freeze the source website.
Handle partial output#
Preserve the summary with the records, identify missing fields or incomplete details, and decide whether the result is usable for your workflow. Do not quietly replace an execution error with an empty dataset. If complete coverage is required, confirm that the source contract supports that scope before relying on it.
Read errors and billing before retrying, and include the source, version, and trace identifier in a support request.