Skip to content
KataraKatara documentation

Read authorized agent execution metadata

GET
/katara/v1/orgs/{org_id}/environments/{environment_id}/runs
curl --request GET \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs \
  --header 'Authorization: Bearer <token>'

Each run is as getRun returns it, reconciliation included. With agent_id, that agent’s runs in admission order. Without it, the environment’s runs across agents, newest first; a caller whose key or workload is limited to some agents sees only their runs.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Query Parameters

Section titled “Query Parameters”
agent_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

The agent whose runs to list. Leave it out to list the newest runs across agents.

after
string
>= 1 characters <= 128 characters /^[A-Za-z0-9_-]+$/

The next_cursor of the previous page. With agent_id it is a run ID; without it, an opaque value to pass back unchanged.

limit
integer
>= 1 <= 100

Header Parameters

Section titled “Header Parameters”
X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Optional for reads after sign-in. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json
object
data
required
Array<object>
<= 100 items unique items
object
admission
required

The admitted request retains its exact project and thread selectors when supplied. These identify the canonical project binding; they grant no authority. Optional workspace selection requires the project/thread pair, live usage and an exact matching katara:locus workload grant. The server checks its currently configured immutable workspace agent/version, hosted grant, profile, preset, project and funding. Selection metadata supplies no authority.

object
agent_version
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
grant_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
input_ref
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed value: application/json
size_bytes
required
integer
<= 1048576
budget_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
usage_class
required
Allowed values: simulation test_compute live
paid_test_consent_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
limits
required

The API also checks steps <= decisions, plan changes <= decisions, active and approval seconds <= elapsed seconds, and children/depth are either both zero or both positive. Structured output is a JSON envelope; larger artifacts use content references. Active time includes Activity scheduling, retries and execution. Approval waits consume the cumulative approval and elapsed limits; ordinary delays consume elapsed time only. Counters survive continuation.

object
max_steps
required
integer
>= 1 <= 10000
max_children
required
integer
<= 1000
max_depth
required
integer
<= 16
max_active_seconds
required
integer
>= 1 <= 86400
max_elapsed_seconds
required
integer
>= 1 <= 2592000
max_approval_wait_seconds
required
integer
>= 1 <= 604800
max_output_bytes
required
integer
>= 1 <= 1048576
max_decisions
required
integer
>= 1 <= 20000
max_plan_changes
required
integer
>= 1 <= 1000
mode
required
Allowed values: test live
reset_generation
required
integer
>= 1 <= 9007199254740991
organization_epoch
required
integer
>= 1 <= 9007199254740991
environment_epoch
required
integer
>= 1 <= 9007199254740991
access_revision
required
integer
>= 1 <= 9007199254740991
requested_by
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
request_key_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
request_service_account_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
output_target
required

Explicit destination for run artifacts. Store and key versions must still be active at admission and byte access. Choose retention from 60 seconds to 365 days; no silent default or destination substitution.

object
store_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
store_version
required
integer
>= 1 <= 9007199254740991
key_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
key_version
required
integer
>= 1 <= 9007199254740991
retention_seconds
required
integer
>= 60 <= 31536000
workload_grants
required
Array<object>
>= 1 items <= 8 items unique items
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
audience
required
Allowed values: katara:synapse katara:locus
project_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
thread_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
workspace

Explicit hosted workspace selection. The selected workload grant must have this exact grant_id and audience katara:locus. Profile and preset identify server-owned configuration; these names do not establish current authority or select a client-supplied agent version.

object
grant_id
required
string format: uuid
>= 36 characters <= 36 characters /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
profile
required
string
>= 1 characters <= 64 characters /^[a-z0-9][a-z0-9-]{0,63}$/
/[^a-z0-9-]/
preset
required
string
>= 1 characters <= 64 characters /^[a-z0-9][a-z0-9-]{0,63}$/
/[^a-z0-9-]/
digest
required
string
/^sha256:[a-f0-9]{64}$/
status
required
Allowed values: queued starting running waiting completed failed cancelled reconciliation_required
reason
Allowed values: completed cancelled authority_denied product_access queue_expired step_limit decision_limit plan_limit time_limit active_time_limit approval_wait_limit budget_exhausted insufficient_funds dependency_failed dependency_unavailable invalid_plan cannot_complete execution_unknown orchestration_unknown child_limit output_blocked output_held
projection_version
required
integer
>= 1 <= 9007199254740991
created_at
required
string format: date-time
changed_at
required
string format: date-time
observation

What a customer is told about a run that has started. The execution engine’s own identifier for the work is not reported: the run id every Katara API takes is the one to use, and an identifier into a system the caller cannot reach answers nothing.

object
snapshot
object
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed values: test live
usage
required
Allowed values: simulation test_compute live
status
required
Allowed values: running waiting completed failed cancelled reconciliation_required
reason
Allowed values: completed cancelled authority_denied product_access queue_expired step_limit decision_limit plan_limit time_limit active_time_limit approval_wait_limit budget_exhausted dependency_failed dependency_unavailable invalid_plan cannot_complete execution_unknown orchestration_unknown child_limit output_blocked output_held
steps
required
integer
<= 10000
decisions
required
integer
<= 20000
plan_revision
required
integer
<= 1000
started_ms
required
integer
>= 1 <= 253402300799999
deadline_ms
required
integer
>= 1 <= 253402300799999
active_ms
required
integer
<= 86400000
approval_ms
required
integer
<= 604800000
wait_kind
Allowed values: approval delay child
last
object
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed values: test live
usage
required
Allowed values: simulation test_compute live
step
required
integer
>= 1 <= 10000
operation_id
required
string
/^sha256:[a-f0-9]{64}$/
outcome
required
Allowed values: succeeded denied failed unknown
output
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
output
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
children
integer
<= 1000
pending_child
object
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed values: test live
usage
required
Allowed values: simulation test_compute live
sequence
required
integer
>= 1 <= 20000
child_run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
action
required
Allowed values: spawn join
request
object
agent_version
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
input_ref
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
media_type
required
Allowed value: application/json
size_bytes
required
<= 1048576
maximum
required
string
/^[1-9][0-9]{0,17}$/
last_child
One of:
object
key
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed values: test live
usage
required
Allowed values: simulation test_compute live
sequence
required
integer
>= 1 <= 20000
child
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
agent_version_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
reset_epoch
required
integer
>= 1 <= 9007199254740991
mode
required
Allowed values: test live
usage
required
Allowed values: simulation test_compute live
state
required
Allowed values: queued starting running waiting
reason
Allowed values: completed cancelled authority_denied product_access queue_expired step_limit decision_limit plan_limit time_limit active_time_limit approval_wait_limit budget_exhausted insufficient_funds dependency_failed dependency_unavailable invalid_plan cannot_complete execution_unknown orchestration_unknown child_limit output_blocked output_held
output
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
Any of:
terminal
required
boolean
requires_reconciliation
required
boolean
cancellation
object
requested_by
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
requested_at
required
string format: date-time
state
required
Allowed values: pending dispatching delivered unresolved
delivered_at
string format: date-time
reconciliation

Present once a person has resolved a run that ended awaiting reconciliation. The run keeps the status reconciliation_required; who resolved it, the evidence and the note are in the run’s reconciliation record.

object
outcome
required
string
Allowed values: effect_completed effect_not_completed corrective_action cancellation_finalized
recorded_at
required
string format: date-time
next_cursor
string
>= 1 characters <= 128 characters /^[A-Za-z0-9_-]+$/
Example
{
  "data": [
    {
      "admission": {
        "input_ref": {
          "media_type": "application/json"
        },
        "usage_class": "simulation",
        "mode": "test",
        "workload_grants": [
          {
            "audience": "katara:synapse"
          }
        ]
      },
      "status": "queued",
      "reason": "completed",
      "observation": {
        "snapshot": {
          "key": {
            "mode": "test",
            "usage": "simulation"
          },
          "status": "running",
          "reason": "completed",
          "wait_kind": "approval",
          "last": {
            "key": {
              "mode": "test",
              "usage": "simulation"
            },
            "outcome": "succeeded",
            "output": {
              "media_type": "text/plain"
            }
          },
          "output": {
            "media_type": "text/plain"
          },
          "pending_child": {
            "key": {
              "mode": "test",
              "usage": "simulation"
            },
            "action": "spawn",
            "request": {
              "input_ref": {
                "media_type": "application/json"
              }
            }
          },
          "last_child": {
            "key": {
              "mode": "test",
              "usage": "simulation"
            },
            "child": {
              "mode": "test",
              "usage": "simulation"
            },
            "state": "queued",
            "reason": "completed",
            "output": {
              "media_type": "text/plain"
            }
          }
        }
      },
      "cancellation": {
        "state": "pending"
      },
      "reconciliation": {
        "outcome": "effect_completed"
      }
    }
  ]
}

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}