# List occurrences Lists the automation's occurrences, newest first: what fired, when, and the run it produced, if any. `GET /v1/users/{userId}/automations/{automationId}/history` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ] ``` ## Query parameters ```json [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" } ] ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request GET 'https://api.example.test/v1/users/YOUR_USER_ID/automations/YOUR_AUTOMATION_ID/history' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' ``` ## Responses ### 200 The automation's occurrences. ```json { "description": "The automation's occurrences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationOccurrence" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 412 The identity is verified but has no account yet. - `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first ```json { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limiter refused the request; honour `Retry-After`. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` ```json { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The replica is draining or a dependency did not answer; `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "automations.history", "summary": "List occurrences", "tags": [ "automations" ], "description": "Lists the automation's occurrences, newest first: what fired, when, and the run it produced, if any.", "parameters": [ { "schema": { "type": "string", "maxLength": 256 }, "in": "query", "name": "cursor", "required": false, "description": "Where the previous page ended; omit for the first page" }, { "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "How many rows to answer, at most 100" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "automationId", "required": true, "description": "The automation's id." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "200": { "description": "The automation's occurrences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationOccurrence" }, "description": "This page's rows." }, "nextCursor": { "description": "The cursor for the next page; null once there are no more rows.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many rows the list holds in all." } }, "required": [ "data", "nextCursor", "total" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "schemas": { "AutomationOccurrence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The occurrence's id." }, "deliverySequence": { "type": "string", "pattern": "^[1-9]\\d*$", "description": "This occurrence's place in its automation's delivery order, as a string so it sorts and compares exactly at any size." }, "automationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The automation's id." }, "definitionVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The automation definition version this occurrence fired under." }, "activationEpoch": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The activation epoch this occurrence fired under." }, "name": { "type": "string", "description": "The automation's name at the time this occurrence fired." }, "prompt": { "type": "string", "description": "The automation's prompt at the time this occurrence fired." }, "evidence": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "decision", "manual", "external" ], "description": "What produced this occurrence: `decision` the rule's own condition, `manual` an owner's invoke or signal, `external` a source that decided on the engine's behalf." }, "identity": { "type": "string", "minLength": 1, "maxLength": 256, "description": "A stable string identifying this exact decision, used to deduplicate replays." }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this decision was made." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" }, "description": "The observations behind one decision, exactly as evaluated. Bounded to 256 KiB, 24 levels of nesting and 16384 entries." }, "sourceChecks": { "description": "Recipe checks recorded for each source this decision read, when evidence review is configured.", "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "binding": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]{0,31}$", "description": "The binding this check was collected for." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The source's id within its provider." }, "eventId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The specific event or observation this check backs." }, "operationId": { "type": "string", "pattern": "^[a-z][a-z0-9_.-]{0,79}$", "description": "The collection operation this check ran." }, "operationVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The collection operation's version." }, "check": { "type": "object", "properties": { "recipe": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The recipe description's own version, bumped when its steps change." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The recipe's short label, for the reviewed catalog." }, "summary": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What the recipe does, for the reviewed catalog." }, "steps": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The step's identifier, unique within its recipe." }, "kind": { "type": "string", "enum": [ "request", "validate", "calculate" ], "description": "What this step does: `request` calls the provider, `validate` checks what it returned, `calculate` derives a value from earlier steps." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The step's short label, for the reviewed catalog." }, "description": { "type": "string", "minLength": 1, "maxLength": 600, "description": "What this step does, for the reviewed catalog." }, "api": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "GRAPHQL" ], "description": "The request's method or protocol." }, "resource": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^\\/?[A-Za-z0-9_{}][A-Za-z0-9_./{} -]*$", "description": "The request's path or resource name." } }, "required": [ "method", "resource" ], "description": "The request this step makes, when it calls the provider." } }, "required": [ "id", "kind", "title", "description" ] }, "description": "The recipe's steps, in order." }, "limitations": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 600 }, "description": "What the recipe does not cover, in the reviewer's own words." }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "A content hash identifying this exact recipe, independent of execution or connection identity." } }, "required": [ "version", "title", "summary", "steps", "limitations", "fingerprint" ], "description": "A reviewed, public description of how a source is collected: the steps a reviewer confirmed, never an executable request or a resolved private endpoint." }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check began." }, "completedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this check finished." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether every step completed." }, "steps": { "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,47}$", "description": "The declared recipe step this check reports on." }, "outcome": { "type": "string", "enum": [ "completed", "failed" ], "description": "Whether the step completed or failed." }, "requestCount": { "description": "How many requests this step made, when it made any.", "type": "integer", "minimum": 0, "maximum": 100000 }, "itemCount": { "description": "How many items this step processed, when counting applies.", "type": "integer", "minimum": 0, "maximum": 1000000 }, "durationMs": { "description": "How long this step took, in milliseconds.", "type": "integer", "minimum": 0, "maximum": 600000 }, "reason": { "description": "Why the step failed, when it did: `not_configured` the source lacks a needed setting, `unavailable` the provider did not answer, `malformed` its answer could not be read, `oversized` the answer exceeded a bound, `stale` or `future` a timestamp was out of range, `incomplete` part of the answer was missing, `invalid` the answer failed validation, `canceled` the check was stopped before finishing.", "type": "string", "enum": [ "not_configured", "unavailable", "malformed", "oversized", "stale", "future", "incomplete", "invalid", "canceled" ] } }, "required": [ "stepId", "outcome" ], "description": "One recipe step's recorded outcome: counts and a closed reason only, never a URL, body, cursor, address or error message." }, "description": "Each step's own recorded outcome, in order." } }, "required": [ "recipe", "startedAt", "completedAt", "status", "steps" ], "description": "A recorded run of a recipe's steps against the real source, kept as evidence." } }, "required": [ "binding", "sourceId", "eventId", "operationId", "operationVersion", "check" ], "description": "Frozen recipe evidence tied to the actual observation used by one decision." } } }, "required": [ "kind", "identity", "evaluatedAt", "data" ], "description": "What triggered this occurrence: the decision, its evaluated data, and any recipe checks behind it." }, "state": { "type": "string", "enum": [ "pending", "deferred", "accepted", "rejected", "canceled", "skipped", "coalesced" ], "description": "This occurrence's delivery state: `pending` waiting to run, `deferred` an admission attempt failed and is waiting to retry, `accepted` handed to a run, `rejected` the delivery policy refused it outright, or a non-retryable admission failure (or an exhausted retry deadline) stopped it, `canceled` stopped before running, `skipped` a previous occurrence was still active, `coalesced` merged into a newer match." }, "reason": { "description": "Why the occurrence is in this state, when there is one to give.", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When this occurrence was recorded." }, "deliveryDeadline": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "The latest this occurrence could still be delivered." }, "nextAttemptAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When the engine will next try to deliver this occurrence." }, "lastAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ], "description": "When the engine last tried to deliver this occurrence, when it has tried." }, "attempts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many delivery attempts this occurrence has had." }, "conversationId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, { "type": "null" } ], "description": "The conversation this occurrence ran in, once it has one." }, "runId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ], "description": "The run this occurrence produced, once it has one." }, "runStatus": { "anyOf": [ { "type": "string", "enum": [ "running", "paused", "completed", "failed", "aborted" ] }, { "type": "null" } ], "description": "That run's status, once it has one: `running`, `paused` while an approval waits, then `completed`, `failed` or `aborted`." }, "runError": { "description": "Why the run failed, when it did.", "type": [ "string", "null" ] }, "pendingApprovals": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "How many approvals this occurrence's run is waiting on." } }, "required": [ "id", "deliverySequence", "automationId", "definitionVersion", "activationEpoch", "name", "prompt", "evidence", "state", "reason", "createdAt", "deliveryDeadline", "nextAttemptAt", "lastAttemptAt", "attempts", "conversationId", "runId", "runStatus", "runError", "pendingApprovals" ], "description": "One firing of an automation: what evidence triggered it, its delivery state, and the run it produced, if any." }, "AutomationJsonValue": { "description": "Any JSON value: a string, number, boolean, null, array or object, nested to any depth.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/AutomationJsonValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/AutomationJsonValue" } } ] }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_completed", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "credential_expired", "account_disabled", "account_not_provisioned", "provider_unavailable", "engine_unavailable", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "rate_limited", "stream_capacity", "invalid_cursor" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "AccountNotProvisioned": { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } } ```