Skip to content
KataraKatara documentation
This is the staging documentation, where Katara rehearses releases. Live and Test both settle on Avalanche Fuji in test USDC here.

Read an ordered trace export page

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

Requires both synapse:runs:export and synapse:runs:read, the original requester, current resource access, and available configured trace retention. Workload credentials cannot export. Every read rechecks the source, key, environment reset and retention; unavailable or changed records fail the whole page. The export contains recorded metadata only.

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
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
export_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

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.

Query Parameters

Section titled “Query Parameters”
after
integer
<= 10000
limit
integer
>= 1 <= 100

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json
object
manifest
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
reset_generation
required
integer
>= 1 <= 9007199254740991
schema_version
required
Allowed value: 1
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
created_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/
expires_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/
retention_version
required
integer
>= 1 <= 9007199254740991
record_count
required
integer
>= 1 <= 10000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
data
required
Array<object>
<= 100 items
object
ordinal
required
integer
>= 1 <= 10000
record
required
object
event
required
object
schema_version
required
Allowed value: 1
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
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_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
usage_record_id

Exact scoped reservation/outcome record. Its presence does not imply a settled charge.

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
mode
required
Allowed values: test live
usage_class
required
Allowed values: simulation test_compute live
reset_generation
required
integer
>= 1 <= 9007199254740991
kind
required
Allowed values: run model tool memory policy retrieval evaluation sandbox
outcome
required
Allowed values: completed failed denied cancelled unknown waiting
reason
required
Allowed values: none permission_denied budget_exhausted approval_required dependency_unavailable timeout cancelled output_invalid effect_unknown execution_failed
run_started_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/
started_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/
ended_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/
agent
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}$/
implementation
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}$/
policy
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}$/
memory
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}$/
counts
required
object
input_tokens
required
integer
<= 9007199254740991
output_tokens
required
integer
<= 9007199254740991
items
required
integer
<= 9007199254740991
integrity
required
string
/^sha256:[a-f0-9]{64}$/
source_version
required
integer
>= 1 <= 9007199254740991
delivery
required
Allowed values: pending delivered unavailable
next_cursor
integer
>= 1 <= 9999
Example
{
  "manifest": {
    "schema_version": 1
  },
  "data": [
    {
      "record": {
        "event": {
          "schema_version": 1,
          "mode": "test",
          "usage_class": "simulation",
          "kind": "run",
          "outcome": "completed",
          "reason": "none"
        },
        "delivery": "pending"
      }
    }
  ]
}

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"
  }
}