Run states and error categories

The complete enums for routine status, run state, trigger, step kind, and error category.

These enums are shared between the API, the dashboard, and webhook payloads.

Routine status

draft | active | paused | archived

Value	Schedulable	Runnable manually
`draft`	No	Yes
`active`	Yes	Yes
`paused`	No	Yes
`archived`	No	No

Run state

queued | claimed | running | succeeded | failed | cancelled | timed_out

Terminal states are succeeded, failed, cancelled, and timed_out. Poll for membership of that set.

Run trigger

manual | api | schedule

Only a successful manual run satisfies the activation requirement.

Step kind

model | tool_call | tool_result | error

Error category

authentication | configuration | gateway_rate_limit | gateway_timeout |
gateway_error | invalid_model | model_auth_required | model_access_denied |
model_unavailable | model_rate_limited | model_runtime_unavailable |
model_timeout | model_provider_error | mcp_discovery | mcp_transport |
reauthorization_required | provider_permission_denied | provider_rate_limit |
provider_policy_blocked | external_action_unknown | tool_denied | tool_error |
step_limit | idle_timeout | timeout | cancelled | billing_limit | internal

step_limit marks the fixed platform safety ceiling of 10,000 model steps — an anti-runaway backstop, retired as a configurable cap. Runs are otherwise bounded by time: timeout covers the absolute deadline (the routine's timeoutSeconds, or on the hosted scheduler the smaller platform execution window — see Limits), and idle_timeout covers a run that recorded no progress within its idleTimeoutSeconds.

Category	Retryable
`authentication`	No
`configuration`	No
`gateway_rate_limit`	Yes
`gateway_timeout`	Yes
`gateway_error`	Yes
`invalid_model`	No
`model_auth_required`	No
`model_access_denied`	No
`model_unavailable`	No
`model_rate_limited`	No
`model_runtime_unavailable`	No
`model_timeout`	No
`model_provider_error`	No
`mcp_discovery`	No
`mcp_transport`	Yes
`reauthorization_required`	No
`provider_permission_denied`	No
`provider_rate_limit`	No
`provider_policy_blocked`	No
`external_action_unknown`	No
`tool_denied`	No
`tool_error`	No
`step_limit`	No
`idle_timeout`	Yes
`timeout`	Yes
`cancelled`	No
`billing_limit`	No
`internal`	No

Webhook retryability is derived from the fixed webhook category mapping. In version one, only gateway_error, gateway_rate_limit, gateway_timeout, idle_timeout, mcp_transport, and timeout produce run.error.retryable: true; every connected-provider model_* category produces false. The webhook payload does not preserve a provider result's retryable value. Any in-attempt runtime retry inside the active provider operation is separate from this webhook contract. Consumers should use the emitted webhook value and the fixed Troubleshooting recovery guidance rather than infer retryability from provider behavior.

Run usage

{
  inputTokens: number; // integer, ≥ 0
  outputTokens: number; // integer, ≥ 0
  totalTokens: number; // integer, ≥ 0
  costUsd: number | null; // webhook/shared aggregate; null when cost is unknown
}

Usage appears on each model step and aggregated on the run. Run detail exposes its preserved cost as an exact decimal string or null; connected-provider missing cost means billed/limited by that provider, not zero. The current database field is text and legacy producers used String(number), so consumers must validate it conservatively rather than assuming every stored value is a canonical decimal or recomputing billing.