Skip to content
Farcaster

List invocations

GET
/v1/invocations
curl --request GET \
  --url 'https://example.com/v1/invocations?status=pending&mode=transactional&settlement=pending&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
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
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",
      "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