Skip to content
Farcaster

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