Execution Tracking

Every time your agent runs, Trappr captures the complete execution — from the trigger that started it to the last LLM call it made. Use execution records to audit agent behavior, investigate incidents, and track costs.

What is an execution?

An execution is one complete run of your agent — a single workflow trigger in n8n, one Make scenario run, or one LangChain agent invocation. Trappr uses execution tokens (chtx_XXXX) to group all activity from a single run: LLM calls, tool outputs, security events, and timing.

Starting an execution

To start an execution, call the Trappr API at the beginning of your agent's run. You receive a token that you attach to all subsequent gateway calls so they're grouped together.

curl -X POST https://api.trappr.net/v1/agents/executions \
  -H "Authorization: Bearer <your-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "cht_agent_XXXX",
    "metadata": {
      "trigger": "webhook",
      "workflowName": "customer-support-v2"
    }
  }'

# Response
{
  "token": "chtx_abc123...",
  "expiresAt": "2026-06-18T14:00:00Z"
}

import httpx

resp = httpx.post(
    "https://api.trappr.net/v1/agents/executions",
    headers={"Authorization": f"Bearer {AGENT_KEY}"},
    json={
        "agentId": "cht_agent_XXXX",
        "metadata": {"trigger": "schedule"},
    },
)
execution_token = resp.json()["token"]  # chtx_...

Attaching the token to gateway calls

Pass the execution token in the X-Trappr-Execution header on every LLM call made during this execution. The gateway automatically associates those calls with the execution.

client = openai.OpenAI(
    base_url="https://gateway.trappr.net/v1",
    api_key=AGENT_KEY,
    default_headers={
        "X-Trappr-Execution": execution_token,
    },
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
)

const client = new OpenAI({
  baseURL: "https://gateway.trappr.net/v1",
  apiKey: AGENT_KEY,
  defaultHeaders: {
    "X-Trappr-Execution": executionToken,
  },
});

Sending heartbeats

For long-running executions, send periodic heartbeats so Trappr doesn't mark the execution as timed out. We recommend every 30 seconds for executions that may run longer than 2 minutes.

curl -X POST https://api.trappr.net/v1/agents/executions/heartbeat \
  -H "Authorization: Bearer <your-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{ "token": "chtx_abc123..." }'

Completing an execution

When your agent finishes, mark the execution as complete. Include the final status and any output metadata you want to associate with the record.

curl -X PATCH https://api.trappr.net/v1/agents/executions/chtx_abc123 \
  -H "Authorization: Bearer <your-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "output": {
      "itemsProcessed": 42,
      "errors": 0
    }
  }'

Viewing executions

All executions are visible under Dashboard → Agents → [Your Agent] → Executions. Each record shows:

• Start time, end time, and duration
• Total LLM calls and token usage
• Estimated cost
• Security events (DLP matches, canary triggers, policy violations)
• Final status