AgentRun

An AgentRun is one execution of an Agent against one Email. AgentRuns are append-only: written by the worker, read-only via the API.

Purpose

• Provide a per-execution audit trail (model, tokens, cost, duration).
• Allow debugging of failures without re-running.
• Aggregate cost back to the workspace's monthly counters.

Schema

Field	Type	Description
id	UUID	Internal id.
workspace_id	UUID	Owning workspace.
inbox_id	UUID	Inbox that produced the email.
agent_id	UUID	Agent that ran.
email_id	UUID	Target email.
llm_model	string	Resolved model id at run time (frozen — Agent.llm_model may have changed since).
status	enum	running, success, failed.
error	string | null	Stack trace / message when status=failed.
input_tokens	int	Prompt tokens (system + user).
output_tokens	int	Completion tokens.
cache_read	int	Tokens served from prompt cache.
cache_write	int	Tokens written to prompt cache.
cost_per_token	decimal	Blended USD/token at execution time.
total_cost	decimal	cost_per_token * (input + output), after cache discounts.
duration_ms	int | null	Wall time of the LLM call.
started_at	datetime | null	Set when the run leaves the queue.
finished_at	datetime | null	Set on terminal state.
created_at / updated_at / deleted_at	datetime

Example

{
  "id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "inbox_id": "b3c4d5e6-7a89-4b0c-9d1e-2f3a4b5c6d7e",
  "agent_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "email_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "llm_model": "anthropic/claude-sonnet-4-6",
  "status": "success",
  "error": null,
  "input_tokens": 1842,
  "output_tokens": 312,
  "cache_read": 1200,
  "cache_write": 642,
  "cost_per_token": "0.00000400",
  "total_cost": "0.00328400",
  "duration_ms": 4127,
  "started_at": "2026-05-17T10:00:14.700Z",
  "finished_at": "2026-05-17T10:00:18.827Z",
  "created_at": "2026-05-17T10:00:14.500Z",
  "updated_at": "2026-05-17T10:00:18.827Z",
  "deleted_at": null
}

Reading

Method	Path
GET	/agent-runs?agent_id=…&email_id=…
GET	/agent-runs/{id}

Filters: agent_id, inbox_id, email_id, status, created_at[gte|lt].

No write endpoints

AgentRuns are created by the worker. To re-execute an agent against an email use POST /v1/emails/{id}/reprocess; a new AgentRun row will be produced.