Skip to content
Zerker Gateway

Get an invocation

GET
/v1/invocations/{id}
curl --request GET \
  --url https://example.com/v1/invocations/example \
  --header 'Authorization: Bearer <token>'

Full invocation metadata for the caller’s tenant. req_body/resp_body are included only when body capture was on for the row and the caller’s token carries the invocations:read_body OAuth scope (spec 0003 §4/§5); otherwise the fields are omitted while body_captured still reflects whether capture was on.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The inv_<uuidv7> invocation ID.

Responses

Section titled “Responses”

200

Section titled “200”

The invocation.

Media typeapplication/json

Same shape as InvocationListItem plus body-capture fields.

object
id
required
string
agent_id
required
string
mode
required
string
Allowed values: transactional streaming
status
required
string
Allowed values: pending running succeeded failed
error_class
required
string
nullable
Allowed values: timeout upstream_5xx upstream_4xx ssrf_blocked credential_error cancelled internal
model
required
string
nullable
mcp_method
required
string
nullable
mcp_tool
required
string
nullable
payment_network
required
string
nullable
payment_asset
required
string
nullable
payment_amount
required
string
nullable
payment_payer
required
string
nullable
payment_nonce
required
string
nullable
policy_action
required

What the policy engine decided about this call, recorded at the moment the decision was made (spec 0009). Null means no decision applied — the tenant has no policy document — which is a different fact from allow and must not be read as one. deny never appears: a denied call returns before the invocation is created, so the absence of denials here is not evidence that nothing is being denied. Read the policy decision log for those.

string
nullable
Allowed values: allow warn
receipt_artifact_id

The Treeship artifact signed for this invocation, or null when none was recorded. Null is not proof none exists — emission is fail-open. The receipt itself is at GET /v1/invocations/{id}/receipt.

string
nullable
policy_matched_rule
required

The 1-based position of the rule that produced policy_action, or an empty string when the tenant’s configured default applied because no rule matched. Null whenever policy_action is null.

string
nullable
settlement
object
status
required
string
Allowed values: pending settled settlement_failed settled_upstream_failed
tx_hash
string
settled_amount

Smallest-unit decimal string.

string
operator_amount

Settled_amount minus facilitator_fee.

string
facilitator_fee

Absent on a self-hosted facilitator that reports no fee.

string
attempts
integer
reason

Coarse failure reason; never raw facilitator response bytes.

string
settled_at
string format: date-time
upstream_status
required
integer
nullable
latency_ms
required
integer format: int64
nullable
ttft_ms
required
integer format: int64
nullable
req_size
required
integer format: int64
nullable
resp_size
required
integer format: int64
nullable
body_captured
required

Whether capture was on for this invocation, regardless of whether the caller’s scope allows reading the bodies.

boolean
req_body

Base64-encoded, capped at 1 MiB. Present only when body_captured and the caller holds the invocations:read_body scope.

string format: byte
resp_body

Base64-encoded, capped at 1 MiB. Present only when body_captured and the caller holds the invocations:read_body scope.

string format: byte
created_at
required
string format: date-time
completed_at
required
string format: date-time
nullable
Example
{
  "mode": "transactional",
  "status": "pending",
  "error_class": "timeout",
  "policy_action": "allow",
  "settlement": {
    "status": "pending"
  }
}

401

Section titled “401”

Missing or invalid bearer token, or the token’s tenant/user claims are absent. No body.

404

Section titled “404”

No resource with this ID exists in the caller’s tenant.

Media typeapplication/json

The uniform error body for all 4xx responses that carry one.

object
error
required

A coarse, caller-safe message. Never contains internal state (invariant

string
Examplegenerated
{
  "error": "example"
}

500

Section titled “500”

An unexpected server-side error. No body (internal detail is never returned to callers, invariant