Docs
Sign inStart free

Operation Lifecycle

An operation is one unit of Chab work. Some operations complete in the same HTTP request. Longer operations return an operation ID that can be checked later.

POST /v1/examples/echo creates a real non-billable operation when simulate_async=true. Use the operation endpoints to list history, poll status, long-poll briefly, and fetch retained results.

Statuses

  • queued: operation is waiting for work.
  • running: work is active. Chab may also show running while waiting on a provider or backing off before a retry; those internal substates are not exposed as separate public statuses.
  • cancelling: cancellation was accepted and cleanup is active. Customer cancellation is cooperative; the operation later reaches cancelled or another terminal state if completion wins the race first.
  • succeeded: result is available.
  • failed: terminal failure.
  • cancelled: terminal cancellation.
  • timed_out: terminal timeout.
  • expired: result or artifacts aged out.

Warnings do not create a separate terminal state. Partial success is returned as succeeded with structured warning objects unless the endpoint documents a typed failure.

Warning objects have this shape:

{
  "code": "partial_results",
  "message": "Some optional result blocks were not available.",
  "field": "blocks.rich_results",
  "severity": "warning"
}

code can be partial_results, field_unavailable, unsupported_field, stale_data, low_confidence, duplicate_candidate, result_truncated, or provider_degraded. severity is info or warning. field is nullable and points to the affected result path when one applies.

Some operation results include field availability metadata. The canonical values are available, missing, unsupported, unavailable, withheld, stale, low_confidence, and unknown. Numeric metrics do not use 0 to mean absent; check availability instead.

Credit Timing

For billable operations, Chab estimates credits before work starts. Credits are held by the time an operation reaches queued or running. The hold is charged when the operation reaches a terminal charged state such as succeeded, or a partially charged cancelled state. A failure or cancellation releases the hold only when Chab confirms that no provider cost was incurred or explicitly waives a Chab-caused failure; uncertain dispatched work stays reserved for review.

Once a billable provider start has been dispatched, a timeout, revoked credential, or cancellation may leave the operation active while Chab verifies the actual provider cost. The reservation remains held, not charged, during this review. Chab may poll only the already-started provider task to settle cost; this does not restore access to cancelled or revoked work. An unknown outcome can require support review and has no guaranteed automatic resolution time. The status object exposes billing_pending: true and cost_reconciliation (automatic_review or operator_review) while this is happening. The result endpoint returns operation_result_not_ready with the same details. This is a held-but-not-charged state, even if the ordinary status remains running or cancelling for compatibility. When an accepted provider task already has a known fixed cost, a customer cancellation or credential revocation may instead end without a result and settle that incurred cost. Chab-caused failures are waived. An unprovable provider outcome stays pending for review rather than becoming a guessed zero-cost completion. When a provider definitively rejects a request before accepting work, Chab releases its credit hold. A request that may have reached chargeable work still requires cost review. If you claim a guest trial account after a provider has already accepted chargeable work, that known cost can settle from the guest operation's existing hold even though the guest credential is revoked.

Cancellation charging depends on how much work had started. If Chab can stop before chargeable work begins, the hold is released. If chargeable work already started, the operation family may charge a partial amount up to the active hold and release the remainder.

Scrape operations reserve credits from the requested rendering mode and plan tier, then settle on the actual rendering path. Direct scrape work settles 2 credits. Browser-rendered scrape work settles 10 credits. Pro and Scale auto requests can reserve 10 credits, finish direct-only for 2 credits, and release the unused hold.

For URL-based runtime target failures, target_fetch_blocked releases the hold. target_timeout is charged only when target fetch or browser render work had started. extraction_failed is charged after Chab fetched or rendered target content but could not produce the requested markdown or selector result.

Screenshot operations reserve 10 credits for viewport or element capture and 15 credits for full-page capture. URL-safety failures before browser work release the hold. selector_not_found, capture_timeout, and capture_failed are charged at the reserved screenshot estimate. artifact_creation_failed releases the hold because the captured image could not be persisted for download.

File conversion operations reserve credits from trusted source metadata: 5 credits for text, Markdown, HTML, CSV or TSV; 15 for Word, Excel, PowerPoint, OpenDocument, RTF or EPUB files; and 20 for PDF with extractable text. Source validation failures, unsupported conversion pairs, and PDFs without extractable text release the hold. Converter timeout or failure is chargeable only after conversion work starts. If Chab cannot start its local converter, the hold is released.

Research operations reserve the full accepted max_credit_budget, then settle from actual normalized token usage and retained cited source count. If the accepted budget is exhausted, Chab returns a partial success when a usable cited report exists; otherwise the operation fails with research_budget_exhausted. Cancellation after research work starts may charge recorded actual work up to the active hold.

Dry Runs

Some operation starts support dry_run=true. Dry runs validate the request, plan access, limits, provider readiness, callbacks, budget, spend threshold, and credit availability without creating an operation, idempotency row, billing hold, callback secret, provider work record, artifact, risk signal, notification, or rate-bucket hit.

For connection-bound starts, this validation includes project authorization, the exact connection and capability, current health/sync state, and any ready-projection requirement. Mutable connection denials release an in-flight idempotency claim so the same key and body can be used after repair. A non-retryable flag means customer remediation is required first; it does not forbid later reuse of the released key.

When an endpoint supports dry run, the live request still requires Idempotency-Key; the dry-run request does not.

Chab rechecks connection access immediately before each later external effect or protected delivery. Removal before provider dispatch fails without provider work. Removal after a durable dispatch boundary can settle only recorded incurred work, blocks later effects and delivery, and uses connection_access_removed. Cancellation remains available to the creating key and does not return protected result data when connection access is gone.

Scrape Operations

Scrape endpoints use the same operation status, callback, polling, result, and artifact lifecycle as other asynchronous operations.

Target URL safety runs before an operation row is created. Direct fetches pin the resolved target and revalidate each redirect before following it. Browser rendering validates the initial target before handoff; after handoff, Chab does not promise direct DNS pinning for browser-provider navigation.

Markdown scrape results can include inline markdown or a customer-visible markdown artifact when the content is large. If requested, raw HTML is exposed as a customer-visible raw_html artifact. DOM scrape results can include inline selector fields or a selector_export artifact for large selector output.

Callbacks receive the same terminal operation events as polling. A scrape callback does not include a different result shape; use the operation result URL to retrieve retained markdown, selector fields, artifacts, and warnings.

Screenshot Operations

Screenshot operations use the same async status, polling, callback, result, and artifact lifecycle as other operations.

Target URL safety runs before an operation row is created. Chab validates and pre-resolves the submitted target before browser handoff, then relies on provider egress isolation after handoff.

Successful screenshot results include capture facts and one customer-visible image artifact with role screenshot. Download the image through the shared operation artifact route before expires_at. After artifact retention elapses, result and artifact retrieval return not_found while terminal operation status and settlement details remain available until operation retention ends.

Convert Operations

Convert operations use the same async status, polling, callback, result, and artifact lifecycle as other operations.

Chab resolves reusable source metadata before reserving credits or reading source content. Dry runs validate source metadata, limits, readiness, callbacks, and credit availability without reading source bytes or creating operation side effects.

Drive Operations

Native-document export uses the same operation polling and result routes as other asynchronous work. It creates a protected drive_export artifact. Removing project or connection access prevents further provider reads and protected artifact delivery.

Successful conversion results include conversion facts and one customer-visible text artifact with role converted_output. Download the artifact through the shared operation artifact route before expires_at. After artifact retention elapses, result and artifact retrieval return not_found while terminal operation status and settlement details remain available until operation retention ends.

Research Operations

Research operations use the same async status, polling, callback, result, and artifact lifecycle as other operations. Live starts require Idempotency-Key; dry runs do not.

Research has a soft adapter timeout before the shared hard operation timeout. At the soft timeout, Chab tries to retrieve current research state and either returns a usable partial result with partial_results or ends with research_timeout. If the shared hard timeout is reached first, the operation uses the standard timed_out lifecycle fallback.

Small research reports and retained sources are inline in the result. Large reports create a research_report artifact plus a paired research_sources_export artifact. The report artifact can be reused only when a consuming operation supports its MIME type. The sources export is download-only.

Polling

Check status with:

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

Chab can return operation.next_check_at or a Retry-After header. Use that hint instead of tight polling loops. For provider-backed operations, these hints may move forward while Chab waits for provider status or backs off after a temporary provider throttle. During that time the public status remains running.

If provider throttling is exhausted, the operation reaches failed with provider_temporarily_rate_limited. The error is retryable and provider-neutral; create a new operation later or retry the original idempotent request when the endpoint allows idempotent replay.

Getting the Result in One Call

Add ?wait=20 (at most 30 seconds) to any start request. Chab waits until the operation finishes and answers with its current state. When it succeeded, the reply also has a result object, in the same shape as the result endpoint returns. If it is still running when the time is up, the reply is the operation as usual. wait is not part of the request's idempotency, so starting again with the same Idempotency-Key and ?wait=20 returns the same operation, now with its result. Only a few requests may wait at the same time; the others get the operation back right away.

curl "https://www.chab.ai/v1/search/web?wait=20" \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-001" \
  -d '{"query":"best espresso machines 2026","engine":"google","location":{"country":"US"},"language":"en"}'

The hosted MCP tool chab_operation_start does the same by default (wait_seconds, 20). Without an idempotency_key, the same tool and input within 10 minutes counts as the same run.

Long Polling

Agents and scripts can wait briefly for a status change:

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

Results

Get a completed result with:

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

Large results are returned as files or artifacts instead of huge inline JSON. LLM generation and embedding results are inline JSON. If model work completes but the inline result is larger than the response limit, the operation fails with response_too_large and settles the model work already performed. LLM operations do not support callbacks, artifacts, streaming, dry-run, provider batch handles, or public fallback routing. Poll the operation status and result endpoints for LLM completion.

Artifacts

Operations can return customer-visible artifact references in status and result responses. An artifact reference includes metadata such as id, type, role, mime_type, byte_size, checksum, filename, metadata_url, download_url, and expires_at.

Artifact metadata and downloads always require bearer authentication. The same team API key must own the operation, and the key must still be authorized for the operation family. Internal and raw artifacts are hidden and return not_found if requested.

Customer-visible result artifacts are retained for the configured result window of 72 hours by default. A team owner can set operation-runtime retention from 24 to 720 hours. Shortening it also shortens eligible existing artifact expiry; increasing it does not restore expired or deleted content. Raw or internal artifacts use a shorter 24 hour default. Large JSON results can be returned as an artifact reference instead of an oversized inline result. Domain backlink operations use JSONL artifacts for large backlink and referring-domain exports, with the same 72-hour customer retention by default. Research operations use research_report and research_sources_export artifacts for large reports. Chab-streamed artifact downloads may be metered as separate egress usage. Team-configurable retention does not extend separately governed billing, policy, audit, security, or legal-hold records.

See Operations for endpoint details, filters, result errors, and pagination.