API: Logs & Tracing

Query execution traces for agents and runners. Every agent turn and runner run produces a trace — a tree of spans capturing LLM calls, tool invocations, webhooks, and other operations.

List Traces

GET /api/logs

Returns a paginated list of traces for the caller's organization.

Parameter	Type	Default	Description
limit	integer	50	Results per page (max 200)
cursor	string	—	Composite cursor (<startedAt>|<traceId>) from a previous response's nextCursor
agent_id	uuid	—	Filter by agent
runner_id	uuid	—	Filter by runner
thread_id	uuid	—	Filter by thread
run_id	uuid	—	Filter by runner run
status	string	—	running, ok, or error
q	string	—	Substring search on trace name

Response:

{
  "traces": [
    {
      "id": "trace-uuid",
      "org_id": "org-uuid",
      "agent_id": "agent-uuid",
      "runner_id": null,
      "thread_id": "thread-uuid",
      "run_id": null,
      "session_id": "sess_abc",
      "user_id": "user_123",
      "name": "chat-turn",
      "status": "ok",
      "started_at": "2026-05-01T12:00:00Z",
      "ended_at": "2026-05-01T12:00:03Z",
      "duration_ms": 3000,
      "total_input_tokens": 1250,
      "total_output_tokens": 480,
      "total_cost_usd": 0.0234,
      "tags": ["production"],
      "span_count": 5,
      "error_count": 0,
      "llm_call_count": 1,
      "tool_call_count": 3
    }
  ],
  "nextCursor": "2026-05-01T12:00:00Z|trace-uuid"
}

# List recent traces for an agent
curl https://api.flapjack.dev/api/logs?agent_id=AGENT_ID&limit=20 \
  -H "Authorization: Bearer fj_live_..."

---

Get Trace Detail

GET /api/logs/{traceId}

Returns the full trace with its span tree and evaluations.

Response:

{
  "trace": {
    "id": "trace-uuid",
    "name": "chat-turn",
    "status": "ok",
    "started_at": "2026-05-01T12:00:00Z",
    "ended_at": "2026-05-01T12:00:03Z",
    "duration_ms": 3000,
    "total_input_tokens": 1250,
    "total_output_tokens": 480,
    "total_cost_usd": 0.0234,
    "tags": [],
    "metadata": {}
  },
  "spans": [
    {
      "id": "span-uuid",
      "trace_id": "trace-uuid",
      "parent_span_id": null,
      "kind": "agent",
      "name": "agent-turn",
      "status": "ok",
      "started_at": "2026-05-01T12:00:00Z",
      "ended_at": "2026-05-01T12:00:03Z",
      "duration_ms": 3000,
      "provider": "anthropic",
      "model": "claude-opus-4-7-20250430",
      "input_tokens": 1250,
      "output_tokens": 480,
      "cached_input_tokens": 800,
      "cost_usd": 0.0234,
      "input": { "messages": ["..."] },
      "output": { "content": "..." },
      "error": null,
      "attributes": {},
      "dotted_order": "1714564800000-span-uuid"
    }
  ],
  "evaluations": [
    {
      "id": "eval-uuid",
      "span_id": "span-uuid",
      "trace_id": "trace-uuid",
      "evaluator": "heuristic.regex",
      "evaluator_version": "1.0",
      "name": "contains_code",
      "score": 1.0,
      "label": "pass",
      "reason": "Response included a code block",
      "metadata": {},
      "created_at": "2026-05-01T12:00:04Z"
    }
  ]
}

---

Concepts

Traces

A trace is the root execution record — one per agent turn or runner run. It carries rollup fields (total_input_tokens, total_output_tokens, total_cost_usd) so list views render without aggregating spans.

Spans

Each operation within a trace is recorded as a span. Spans form a tree via parent_span_id. The dotted_order field (LangSmith-style) enables efficient tree sorting.

Span Kind	Description
agent	Top-level agent execution
runner_step	A single step in a runner pipeline
llm	LLM inference call
tool	Custom tool invocation
mcp	MCP server tool call
webhook	Outbound HTTP call
condition	Conditional flow evaluation
embedding	Embedding generation
guardrail	Guardrail check
chain	Grouped chain of operations

LLM spans include token counts (input_tokens, output_tokens, cached_input_tokens) and cost_usd. Payloads (input, output, error) are truncated to ~256 KB.

Evaluations

Evaluations are scores attached to spans — from heuristics, LLM judges, or human reviewers. Each evaluation has an evaluator identifier, a name, and an optional normalized score (0–1).

Retention

Traces are retained per org plan. The purge_logs_older_than() function handles cleanup (default: 30 days free, 90 days paid).

---

Next Steps

• Concepts: Agents
• API: Runners — runner analytics include per-run tracing
• Runners Developer Guide