Run an API

Execute an accepted source definition and receive structured records with an execution summary. Copy your source identifier, API origin, and full definition version from its connection details in the console.

On this page

POST /v1/sources/{source_id}/run

This reference describes generated source APIs. The saved request and OpenAPI contract for your API define its supported inputs and record schema.

Before you send a request#

Create a server credential with the run scope and access to the source. Keep it in your server's secret store. Add read to retrieve connection details and results to retrieve retained run results. See authentication.

Save one unique idempotency key with the source, definition version, and input before sending the request. Reuse that exact identity when recovering the same request. Create a new key for each intentional new execution.

Headers#

Header	Value
`Authorization`	`Bearer <API_KEY>`
`Content-Type`	`application/json`
`Idempotency-Key`	Required for customer workspace execution. A saved string of 1–200 characters using letters, numbers, `.`, `_`, `:`, or `-`.

The origin comes from your API's connection details. It is separate from the website being collected. Send credentials only to that supplied HTTPS origin.

Request body#

Field	Type	Meaning
`expected_version`	string	Require the active definition to match this full 64-character lowercase SHA-256 version. Recommended for normal execution.
`definition_version`	string	Select an accepted immutable revision explicitly. Use instead of `expected_version`. It applies that revision's rules to current source content.
`input`	object	Inputs accepted by this source's generated contract.
`endpoint`	string	Optional; the supported value is `search`.

Do not combine expected_version and definition_version, including a null value. An inactive candidate is not an accepted revision. A version selects extraction rules; it does not restore an older copy of the website.

For a collection API that supports these inputs, begin with one collection page and no detail enrichment:

umask 077
: "${CLEANEDWEB_IDEMPOTENCY_KEY:?Set the saved key for this request}"

curl --fail-with-body --max-time 60 \
  "${CLEANEDWEB_API_BASE}/v1/sources/${CLEANEDWEB_SOURCE_ID}/run" \
  -H "Authorization: Bearer ${CLEANEDWEB_API_KEY}" \
  -H "Idempotency-Key: ${CLEANEDWEB_IDEMPOTENCY_KEY}" \
  -H 'Content-Type: application/json' \
  --data "{\"expected_version\":\"${CLEANEDWEB_DEFINITION_VERSION}\",\"input\":{\"max_pages\":1,\"detail_limit\":0}}" \
  --output response.json

Set the connection variables as described in the quickstart. Store the request key before executing this command. Use a fresh private directory or a unique output filename for each intended execution, so an earlier response is not overwritten. Keep the response file private.

max_pages is a collection budget, not a page number. detail_limit: 0 disables detail enrichment. Search APIs can require a query instead; use their exact allowed values or constraints. Unknown fields and values outside the accepted contract are rejected.

Response fields#

Field	Meaning
`records`	Array of records conforming to this source's output schema.
`summary.source_id`	Source that executed.
`summary.definition_version`	Full version used for execution. Must match the requested version.
`summary.status`	`completed`, `bounded`, or `partial`.
`summary.within_scope_passed`	Whether execution passed within its requested scope.
`summary.catalog_complete`	The generated contract reports `false`; a run does not establish full-catalog coverage.
`summary.records`	Number of returned records.
`summary.limits`	Collection and detail limits applied to the run.
`summary.details_selected`	Records selected for detail enrichment.
`summary.details_complete`	Selected details that completed.
`summary.details_not_selected`	Records outside the selected detail budget.
`metadata.definition_version`	Execution version; must agree with the summary and requested version.
`artifacts`	Additional execution artifacts. Preserve relevant diagnostics alongside the result.
`traceId`	Trace identifier when available; it may be null.
`delivery`	Present for a delivered customer workspace result: `runId`, `chargeReceiptId`, and `recordCount`.

The generated contract can include additional summary and metadata fields. Keep the complete response so you can review missing fields, collection stop reasons, and other source-specific evidence.

Accept or review the result#

Before downstream processing, require both version fields to match your requested version, summary.within_scope_passed to be true, and summary.status to be completed or bounded. Validate the records against your saved schema and required fields. Compare the returned record count with the records array.

A bounded result can meet the request while leaving later pages or detail records uncollected. Preserve a partial response for review; do not replace it with an empty dataset. HTTP 200 alone does not establish a usable result. See pagination and output.

Retrieve a delivered result#

If you have delivery.runId, retrieve its retained result using a credential with the results scope:

GET /v1/sources/{source_id}/runs/{run_id}/result
Authorization: Bearer <API_KEY>

This reads the saved delivery without collecting the website again. The source, workspace, and run must match. A 404 means the result was not found or is inaccessible; a 409 can mean it is not available for delivery yet.

For a lost response without a run identifier, follow idempotency and recovery. For rejected requests, see errors and retries.