trigger.history

Coming July 20, 2026

List recently dispatched triggers with delivery outcomes.

CategoryTrigger
JSON-RPCtools/call
EndpointPOST /mcp

Description

Returns the dispatch history for the authenticated principal, filterable by handler, status, or action class. The result includes the trigger envelope summary, every delivery attempt, the final outcome (`success` / `failed` / `dlq`), and the linked ledger entry id.

Input schema

FieldTypeRequiredDescription
handler_idstringnoFilter by handler id.
status"success" | "failed" | "dlq" | "all"noFilter by outcome. Defaults to `all`.
action_classstringnoFilter by action class.
limitinteger > 0noMax triggers. Default 50.

Output shape

typescript
{
  triggers: Array<{
    trigger_id: string;
    handler_id: string;
    action_class: string;
    status: "success" | "failed" | "dlq";
    attempts: number;
    dispatched_at: string;
    completed_at?: string;
    ledger_entry_id?: string;
  }>;
}

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

jsontools/call params
{
  "name": "trigger.history",
  "arguments": { "status": "dlq", "limit": 10 }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

jsonparsed result body
{
  "triggers": [
    {
      "trigger_id": "trg_01HXP9DLQ",
      "handler_id": "hnd_01HXP9HANDLER",
      "action_class": "communicate",
      "status": "dlq",
      "attempts": 7,
      "dispatched_at": "2026-05-27T14:31:00Z",
      "ledger_entry_id": "led_01HXP9TRG"
    }
  ]
}

Errors this tool can return

CodeMeaning
unauthorizedMissing or invalid bearer token.
quota_exceededPer-minute, daily call, or daily inference budget exceeded.

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).

Notes