Skip to content
KataraKatara documentation

List runs and actions awaiting reconciliation

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

Requires synapse:runs:read. Runs that ended with an effect nobody could confirm, outstanding ones first, at most 500. Accounting is included for a role that also reads billing. actions lists external runtimes’ actions whose outcome is unknown, for a caller who also holds locus:actions:read, and is empty otherwise. A key sees its own environment 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

Responses

Section titled “Responses”

200

Section titled “200”

Current state.

Media typeapplication/json

The organization’s runs awaiting reconciliation and its external actions whose outcome is unknown, the outstanding ones first, at most 500 of each.

object
data
required
Array<object>
<= 500 items

A run that ended awaiting reconciliation: what is needed to decide, and its resolution once there is one.

object
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
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
mode
required
string
Allowed values: test live
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
agent_name
string
>= 1 characters <= 120 characters
reason
required
string
>= 1 characters <= 80 characters
ended_at
required
string format: date-time
effect

The step whose outcome is unknown: the run’s last.

object
step
required
integer
>= 1 <= 10000
kind
required
string
Allowed values: inference tool recall ingestion code browser
target_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
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
checkpoint_kept
required
boolean
held
required
boolean
resolution

What the person who resolved the reconciliation recorded. Written once and never changed.

object
outcome
required
string
Allowed values: effect_completed effect_not_completed corrective_action cancellation_finalized
reference
required
string
>= 3 characters <= 200 characters
note
string
>= 1 characters <= 2000 characters
recorded_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
recorded_at
required
string format: date-time
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
accounting

The reservation behind the effect, in atomic units, for a role that reads billing.

object
purpose
required
string
Allowed values: inference tool service sandbox evaluation
reserved
required
integer
>= 1 <= 9007199254740991
charged
required
integer
<= 9007199254740991
state
required
string
Allowed values: held unknown charged released
exposure
Array<object>
<= 200 items

One hold tied to the run, in atomic units, for a role that reads billing: the step it belongs to when it belongs to one.

object
kind
required
string
Allowed values: inference tool recall ingestion code browser
step
integer
>= 1 <= 10000
purpose
required
string
Allowed values: inference tool service sandbox evaluation
reserved
required
integer
>= 1 <= 9007199254740991
charged
required
integer
<= 9007199254740991
state
required
string
Allowed values: held unknown charged released
actions

External actions whose outcome is unknown, the outstanding ones first, for a caller who reads actions; empty for one who does not.

Array<object>
<= 500 items

An external runtime’s action whose outcome is unknown, and its resolution once there is one. It carries identifiers, states, amounts and times, never the action’s input or the tool’s output. unit is absent when the action had no tool unit.

object
action_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
mode
required
string
Allowed values: test live
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
resource_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
effect
required
string
Allowed values: read_only idempotent_write non_idempotent_write
claimed_at
required
string format: date-time
outcome
required

The call ended without a reply anyone could trust, so nobody knows whether the effect happened.

string
Allowed value: unknown
observed_at
required
string format: date-time
unit

The action’s one tool unit as its budget holds it.

object
price
required

The tool tariff the action was admitted at, in atomic credit units (nine decimal places).

integer
>= 1 <= 9007199254740991
state
required

Held: reserved and not yet decided. unknown: reserved and marked as awaiting reconciliation once no call could still be running. charged: the unit was spent. released: it was returned to the budget.

string
Allowed values: held unknown charged released
charged
required
integer
<= 9007199254740991
resolution

What the owner or admin who resolved the action recorded. Written once and never changed.

object
outcome
required
string
Allowed values: completed not_completed
reference
required
string
>= 3 characters <= 200 characters
note
required
string
>= 1 characters <= 2000 characters
unit_outcome

What the record did to the unit. Absent when the action had none.

string
Allowed values: charged released
recorded_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
recorded_at
required
string format: date-time
operation_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
Example
{
  "data": [
    {
      "mode": "test",
      "effect": {
        "kind": "inference"
      },
      "resolution": {
        "outcome": "effect_completed"
      },
      "accounting": {
        "purpose": "inference",
        "state": "held"
      },
      "exposure": [
        {
          "kind": "inference",
          "purpose": "inference",
          "state": "held"
        }
      ]
    }
  ],
  "actions": [
    {
      "mode": "test",
      "effect": "read_only",
      "outcome": "unknown",
      "unit": {
        "state": "held"
      },
      "resolution": {
        "outcome": "completed",
        "unit_outcome": "charged"
      }
    }
  ]
}

default

Section titled “default”

Request rejected or unavailable.

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