Skip to content
Zerker Gateway

List invocations

GET
/v1/invocations
curl --request GET \
  --url 'https://example.com/v1/invocations?status=pending&mode=transactional&settlement=pending&policy=allow&limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

Paginated (offset-based), tenant-scoped, filterable invocation history. Bodies are never returned on this endpoint (spec 0003).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
agent_id
string
status
string
Allowed values: pending running succeeded failed
mode
string
Allowed values: transactional streaming
error_class
string

Passed through without validation; an unrecognized value simply returns no results.

model
string
settlement
string
Allowed values: pending settled settlement_failed settled_upstream_failed
policy
string
Allowed values: allow warn

Filter by the policy decision recorded on the invocation. Only allow and warn are accepted — a policy deny returns before the invocation is created, so no invocation can carry one. Rows with no decision (no policy configured) match neither value.

since
string format: date-time

RFC 3339 timestamp; inclusive lower bound on created_at.

until
string format: date-time

RFC 3339 timestamp; inclusive upper bound on created_at.

limit
integer
default: 20 >= 1 <= 100
offset
integer
0

Responses

Section titled “Responses”

200

Section titled “200”

A page of invocations.

Media typeapplication/json
object
data
required
Array<object>
object
id
required

The inv_<uuidv7> resource ID.

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

Time to first byte; null unless the streaming path received at least one byte.

integer format: int64
nullable
req_size
required
integer format: int64
nullable
resp_size
required
integer format: int64
nullable
created_at
required
string format: date-time
completed_at
required
string format: date-time
nullable
total
required
integer
limit
required
integer
offset
required
integer
Example
{
  "data": [
    {
      "mode": "transactional",
      "status": "pending",
      "error_class": "timeout",
      "policy_action": "allow",
      "settlement": {
        "status": "pending"
      }
    }
  ]
}

400

Section titled “400”

An invalid status, mode, settlement, since, or until value.

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

401

Section titled “401”

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

500

Section titled “500”

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