Runs, retries, and cancellation

Every accepted action submission creates or reuses a durable run. Live and async execution share the same inputs, accounting, idempotency, and output shapes.

Choose an execution mode

/run/live attempts to process the work during the request. It can return 202 if capacity is occupied. /run/async queues the run and normally returns 202. An idempotent replay of a completed async run returns its terminal response with HTTP 200.

Neither mode guarantees instant source availability. Use async when your application can poll and does not need to keep a browser request open.

bash

curl "$API_URL/v1/actions/linkedin-extract-company/run/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: company-lookup-001" \
  -d '{"input":{"identifier":"https://www.linkedin.com/company/microsoft/"},"max_results":1,"max_credits":1}'

Poll for completion

Use the returned id to read GET /v1/runs/{id}. Begin with a few seconds between reads, back off while the job is waiting, and stay under the workspace request limit.

bash

curl "$API_URL/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $API_KEY"

State	What your application should do
`queued`	Wait and poll; source capacity has not been acquired.
`processing`	Wait and poll; do not submit replacement work automatically.
`completed`	Read output and credits used.
`failed`	Inspect the run error; check released credits before choosing new work.
`cancelled`	Stop polling; the run is terminal.

The endpoint also exposes GET /v1/runs/{id}/outputs. It returns run_id, status, output, and completeness; it is not a paginated file export.

Retry safely

After a network timeout, repeat the same action, body, and Idempotency-Key. This returns the existing run rather than admitting duplicate work. Keys are scoped to a workspace. A different body or action with a reused key returns 409.

A failed terminal run stays failed when replayed. Use a new key only after deciding to create a new attempt. Retrying with a new key after an ambiguous timeout can duplicate upstream work.

Cancellation

bash

curl -X POST "$API_URL/v1/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

Queued work can be canceled and refunded immediately. For processing work, the API records a pending cancellation; it does not promise to interrupt an upstream request already in flight. Accounting is resolved when the worker settles or its lease expires. Poll the run to see the terminal result.

Expiry and uncertain outcomes

Queued work expires after 15 minutes. A processing lease is considered stale after 120 seconds. The worker fails and refunds stale work instead of automatically reissuing an ambiguous provider request. A late worker cannot overwrite the terminal result.

These mechanisms depend on the worker and recovery schedule running. A deployment without the worker schedule is not a complete async service.

Output completeness

All current list actions return one page, with a maximum of 100 records. has_more can indicate more source results, but there is no continuation cursor yet. There are no completion webhooks or recurring schedules in the public API.

Route availability

An account may be available for one action but lack approval for another. If the provider transport explicitly refuses a route before sending the request, the run can return to queued while another eligible account is selected. Keep polling the same run; do not create another reservation. If no eligible account remains, the run fails with route_unavailable and reserved customer credits are released. Ambiguous provider failures are not automatically replayed.