Run operations and recovery
Operate published workflows with durable run identifiers, exact retry semantics, explicit business outcomes, and value-safe inspection.
Keep a durable run ledger
Before sending a run request, save the workflow ID, active published version ID, exact trigger_data, and an opaque UUID idempotency_key in your protected application store. Reuse the same key only for the same workflow version and identical trigger_data. Do not put PHI or credentials in the key. A fresh key represents a new logical run and can repeat external writes.
{
"idempotency_key": "d7dc9e64-18b0-409e-bf6f-f16945fd915e",
"trigger_data": {
"ready": true
}
}| Outcome | Next action |
|---|---|
| 202 accepted | Persist run_id and observe it. Do not interpret queued/running as completion. |
| Run request timeout | Retry the exact saved request with the same key and version. Do not publish a new version between attempts. |
| 409 on a run | Check active version and whether the key was reused with different inputs. Do not generate a new key to bypass a conflict. |
| 401 / 403 | Correct the organization-bound key, scopes, or plan access. Retrying unchanged credentials cannot repair authorization. |
| 422 | Repair the request or graph using validation findings. Readiness and runtime failures are separate. |
| 429 | Respect Retry-After when supplied and use bounded backoff. Keep the original run key. |
| Import/publish timeout | Read workflow/version state before retrying. Import has no documented idempotency key. Reconcile an unknown import through the workflow list. |
| Uncertain external write | Reconcile the connected record and execution evidence with an authorized operator. Do not automatically replay a non-retry-safe action. |
Inspect the exact run
Use GET /developer/v1/workflows/{id}/runs with status, since, until, and limit as needed. The limit is at most 25 and this endpoint has no offset pagination. Find the exact run_id rather than assuming the newest entry is yours. Use time filters and narrower status windows if it falls outside the returned set. Public node inspection exposes status, types, and counts without values or raw errors. Keep PHI-bearing diagnosis and record reconciliation in the authorized application, outside model logs.
Change versions without changing an in-flight request
Create a draft, edit or replace its complete graph, validate and audit it, then publish. Published versions are immutable. To revert, copy a historical version into a new draft and publish it; this does not undo writes from previous runs. A graph replacement must retain every node and edge you intend to keep. Publishing removed nodes can return 409 with a confirmation contract; inspect the diff before deliberately confirming it.
Cancel and clean up
POST /developer/v1/runs/{run_id}/cancel requests cancellation. Cancellation is not an external-system rollback. DELETE /developer/v1/workflows/{id}?confirm=true soft-deletes the workflow and requires workflow:publish. The quickstart leaves its workflow and state file in place for inspection; delete only the workflow identified in that file when you are finished.
Separate webhook credentials from agent context
Use capabilities/v2 to check public_webhooks.deployment_enabled before authoring a generic webhook_trigger. After publication, an authorized non-LLM credential client retrieves /developer/v1/workflows/{id}/webhook-endpoint using REST. The URL is an execution credential and is intentionally unavailable through MCP. Honor no-store, keep the URL out of prompts and logs, and send a stable Idempotency-Key for exact delivery retries. The public webhook has a separate 30-day idempotency contract and a 256,000-byte JSON-object body limit. Do not assume that retention window applies to REST run requests.