Agent runs and usage

Every execution of an agent over an e-mail, with its tokens, cost and duration — plus the two aggregate views over the same data. Four read-only tools.

See the AgentRun model and the Usage model.

---

agent_runs_list

Read · scope inbox/agent_runs · permission agent-runs.list · GET /agent-runs

List agent executions with tokens, cost and duration. Cursor-paginated.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
status	running | success | failed	Filter by run status.
agent_id	string (uuid)	Only runs of this agent.
email_id	string (uuid)	Only runs over this e-mail.
inbox_id	string (uuid)	Only runs of mail received on this inbox.
llm_model	string	Filter by model, as provider/model.
created_at_gte / created_at_lte	string	ISO 8601 range on created_at.
finished_at_gte / finished_at_lte	string	ISO 8601 range on finished_at.

agent_runs_get

Read · scope inbox/agent_runs · permission agent-runs.show · GET /agent-runs/{id}

Fetch one agent run, including the prompt version it executed and the error when it failed.

Parameter	Type	Description
id required	string (uuid)	Agent run id.

usage_summary

Read · scope inbox/usage · permission usage.show · GET /usage/summary

Aggregated usage for a date range: e-mails processed, runs, tokens and cost. Defaults to the last 30 days.

Parameter	Type	Description
from	string (YYYY-MM-DD)	Inclusive start date.
to	string (YYYY-MM-DD)	Inclusive end date.

usage_cost

Read · scope inbox/usage · permission usage.show · GET /usage/cost

Cost broken down by model for a date range. Defaults to the last 30 days.

Parameter	Type	Description
from	string (YYYY-MM-DD)	Inclusive start date.
to	string (YYYY-MM-DD)	Inclusive end date.