Docs
Sign inStart free

Operations

Operation endpoints let you list, poll, long-poll, fetch retained results, download operation artifacts, and cancel in-flight operations created by the same team API key. Guest trial API credentials can poll, fetch results, cancel, and read/download artifacts for guest operations that belong to the same guest trial, but they do not list operation history. Guest trial promotional credits are one-off grants and do not refresh monthly.

Reads are scoped to the creating API key. If an operation belongs to another team, another key, or a family whose scope the key no longer has, Chab returns not_found.

For guest trial API credentials, reads are scoped to the guest beneficiary instead of a team token. A guest credential can access only guest operations for the same guest and only for operation keys in the guest allowlist. Team operations, project-bound operations, connected-account operations, and other guests' operations return not_found.

Connection-bound operations also require the current project grant, active connection, health/sync state, and exact capability. List, status, result, and artifact reads omit or return not_found after that access is lost. The public operation object may contain project_id and connection_id; accepted policy, state, capability revision, schema, purpose, and decision-version snapshots are kept private and are not published.

GET/v1/operations

List operation history for the authenticated team API key.

curl https://www.chab.ai/v1/operations \
  -H "Authorization: Bearer CHAB_API_KEY"

Filters: status, family, operation_key, token, project, connection, created_after, created_before, and error_code. The token filter can only match the caller's own token.

Responses use cursor pagination:

{
  "data": [
    {
      "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
      "status": "succeeded",
      "operation_key": "examples.echo",
      "family": "examples",
      "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
      "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
      "estimated_credits": 0,
      "result_available": true
    }
  ],
  "meta": {
    "request_id": "req_123",
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false,
    "limit": 50
  }
}

GET/v1/operations/{id}

Get the current operation status.

curl https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K \
  -H "Authorization: Bearer CHAB_API_KEY"

Active operations include next_check_at, and responses may include Retry-After. Use those hints instead of tight polling loops.

Long-poll with wait, either as seconds or with an s suffix:

curl "https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K?wait=30s" \
  -H "Authorization: Bearer CHAB_API_KEY"

Chab clamps long-poll waits to the server maximum and returns the current state when the wait ends.

GET/v1/operations/{id}/result

Fetch the retained inline result for a succeeded operation.

curl https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result \
  -H "Authorization: Bearer CHAB_API_KEY"

{
  "data": {
    "result": {
      "echo": {
        "hello": "world"
      }
    },
    "artifacts": [],
    "warnings": [],
    "result_expires_at": "2026-06-26T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Artifacts

Operations can return protected customer-visible artifacts alongside inline result facts. Artifact references appear in data.artifacts[] on result responses and, when requested by status endpoints, on operation objects.

Reusable input sources

Operations that accept shared input refer to the source as {"type":"artifact_id","id":"art_..."} or, where documented, {"type":"file_id","id":"fil_..."}. The producing workflow owns file upload, safety state, visibility, expiry, and deletion. A consumer such as Artifact roles identify the output kind for that operation family. Domain backlink operations can produce backlinks_export and referring_domains_export JSONL artifacts. Scrape operations can produce markdown, raw_html, and selector_export artifacts. Screenshot operations produce an image artifact with role screenshot. Conversion operations produce converted_output; translation operations can produce translated_output when translated content exceeds the inline result threshold. Research operations can produce research_report and research_sources_export artifacts for large reports. Drive native-document exports produce drive_export artifacts.

Artifact metadata and downloads are authorized like operation status reads: the same team API key must own the operation and still have access to the operation family, or the guest trial API credential must belong to the same guest trial as the guest operation. Unknown, expired, internal, raw, or unauthorized artifacts return not_found.

If a capture or export succeeds but Chab cannot persist the protected artifact, the operation fails with artifact_creation_failed. That error is retryable and not chargeable because the output could not be made available.

GET/v1/operations/{id}/artifacts/{artifact_id}

Fetch protected metadata for a customer-visible artifact produced by an operation.

curl https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K \
  -H "Authorization: Bearer CHAB_API_KEY"

{
  "data": {
    "artifact": {
      "id": "art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
      "type": "jsonl",
      "role": "backlinks_export",
      "mime_type": "application/jsonl",
      "byte_size": 2048,
      "checksum": "sha256:abc123",
      "filename": "seo-domains-backlinks-op_01JZ7H0A1B2C3D4E5F6G7H8J9K.jsonl",
      "metadata_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K",
      "download_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K/download",
      "expires_at": "2026-06-26T12:00:00+00:00"
    }
  },
  "meta": {
    "request_id": "req_123"
  }
}

Artifact metadata is scoped like operation status reads: the same team API key must own the operation and still have access to the operation family, or the guest trial API credential must belong to the same guest trial as the guest operation. Unknown, expired, internal, raw, or unauthorized artifacts return not_found.

GET/v1/operations/{id}/artifacts/{artifact_id}/download

Download a customer-visible artifact after the same authorization checks as the metadata endpoint.

curl -L https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/artifacts/art_01JZ7H0A1B2C3D4E5F6G7H8J9K/download \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -o artifact.bin

Chab either streams the artifact bytes or redirects to a fresh short-lived download URL after authorization. Chab-streamed downloads may meter bandwidth. Redirected downloads do not pass bytes through Chab and do not create an egress charge. Expired or hidden artifacts return not_found.

Domain backlink operations can produce JSONL artifacts with roles backlinks_export and referring_domains_export. Each JSONL file contains one normalized row per line. The inline result's exports[] array carries the row count for each export; match it to the operation artifacts[] entry by role and filename.

Scrape operations can produce customer-visible artifacts for large markdown, raw HTML requested with include_raw_html, or large selector output. These artifacts use roles such as markdown, raw_html, and selector_export.

Screenshot operations produce customer-visible image artifacts with role screenshot.

Conversion operations produce customer-visible text artifacts with role converted_output. Translation operations produce customer-visible text artifacts with role translated_output when the translated result is too large to return inline. Research operations produce research_report artifacts for large reports and paired research_sources_export JSON artifacts for retained source lists. research_sources_export is download-only and cannot be reused as operation input.

POST/v1/operations/{id}/cancel

Request cooperative cancellation for one operation. This endpoint has no JSON body and requires Idempotency-Key.

curl -X POST https://www.chab.ai/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/cancel \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Idempotency-Key: cancel-op-001"

The response is the current operation object. Active operations usually move to cancelling first, then to a terminal state. Cancelling an already-terminal operation is safe and returns its current terminal state. Credit settlement is exactly once: if no chargeable work started, Chab releases the hold; if chargeable work already started, the operation family policy may charge a partial amount and release the remainder.

POST/v1/operations/cancel

Request cancellation for multiple operations selected by explicit IDs or by bounded filters. This endpoint requires Idempotency-Key.

curl -X POST https://www.chab.ai/v1/operations/cancel \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-bulk-001" \
  -d '{"family":"examples","status":"running"}'

Supported filters are operation_ids, token, family, operation_key, project, connection, created_after, created_before, and active status values: queued, running, or cancelling.

{
  "data": {
    "cancelled": [],
    "already_terminal": [],
    "unsupported": [],
    "not_found_or_not_authorized": 0,
    "counts": {
      "cancelled": 0,
      "already_terminal": 0,
      "unsupported": 0,
      "not_found_or_not_authorized": 0
    },
    "capped": false
  },
  "meta": {
    "request_id": "req_123"
  }
}

Bulk cancel is scoped to operations created by the same team API key. Explicit IDs that are missing, belong to another key, or are not authorized are counted only in not_found_or_not_authorized. Filter selection is capped at 100 operations by default; when more rows match, capped is true.

Operation results

If a result is requested before the operation succeeds, Chab returns operation_result_not_ready with HTTP 409 and Retry-After.

Failed, cancelled, timed-out, expired, or retention-elapsed operations return not_found from the result endpoint. Use the status endpoint for terminal reason fields such as public_error_code, warnings, diagnostic_reference, and billable settlement details.

Status and list responses set result_available to true only while a succeeded operation's retained result is still available. After result_expires_at elapses, result_available is false even if the operation row has not yet been marked expired by background reconciliation.

Inline JSON results are capped by the shared inline-size limit. Larger results are returned as artifact references in the result payload. Download the artifact before its expires_at value; after artifact retention elapses, result and artifact retrieval return not_found while terminal status, request ID, and settlement details remain available until the operation runtime reaches its archive and prune retention windows.

Domain backlink exports use customer-visible JSONL artifacts for large backlink and referring-domain sets. Chab-streamed artifact downloads are metered as bandwidth egress separately from the operation's fixed credit price.

Idempotent replay of an operation-creating request returns the original creation response and does not start a duplicate operation.

At acceptance, Chab stores the resolved project and connection decision rather than trusting IDs copied from a display summary. Before every provider start, effectful poll, protected callback attempt, artifact redirect, and first metered response byte, Chab rechecks current access. If access is removed after acceptance, no later protected effect is sent and the operation can finish with connection_access_removed. Work already incurred can still settle; unused holds are released. A dry run performs the same connection decision but creates no operation, hold, callback secret, provider effect, or idempotency row.

The signed-in console's Replay safely action is different: it prepares a new request with a fresh idempotency key. It copies only retained fields that are explicitly classified public in the current request schema and requires sensitive or secret values to be re-entered. See the API Console.

For billable operations, successful terminal settlement charges the final amount capped at the reserved hold. Timeout and cancellation follow the operation family's cancellation policy. Failures with no chargeable work release the hold.