List recent agent traces (one row per trace) newest-first, as a Markdown table.

The trace_id column feeds get_agent_trace. When more traces match than limit, the reply carries a next-page cursor: pass it back as cursor to fetch the next page, rather than raising limit past what a chat can usefully display.

The session column is the ROOT span's session id; pass it to list_spans(session_id=...) to see every span of that conversation across the traces it touched. A span with no session of its own is stamped with its trace id, so a session equal to the row's trace_id means "no session", not a one-trace conversation. Blank where this deployment does not report it yet.

workspace: optional workspace id, name, or org-name/workspace-name when the same name occurs in two of your orgs (defaults to your default; use list_workspaces to discover them). hours: lookback window in hours (default 24), used for whichever of start/end is not given. start: optional absolute RFC3339 lower bound; overrides the hours-derived value when given. end: optional absolute RFC3339 upper bound; overrides the hours-derived value when given. service: optional service-name filter (traces that involve this service). status: optional trace status filter, "Ok", "Error", or "Incomplete". Note a trace reads Error when ANY of its spans errored, so a run that retried a failing step and then succeeded is in here too — read root_status to tell those apart. root_status: optional filter on the ROOT span's own verdict, "Ok", "Error", or "Incomplete". Composes with status rather than replacing it: status="Error" with root_status="Ok" is the recovered slice (children errored, the run itself finished clean), and root_status="Error" alone is the genuine failures. A trace whose root_status column is blank matches neither — the server made no claim about its root. agent: optional exact agent-name filter, matched against the trace's root span — the same value the root_agent column reports, so read a name off a listing rather than guessing one, and pass it back to get every other run of that agent. Agent identity is its own field, not the service name: a run that declares no agent falls back to its service name, so equal root_agent and service columns are that fallback, not two facts. instance: optional exact agent-instance filter, narrowing to one running copy of agent. user_id: optional end-user scope — the exact id, as the user_id column reports it. The END USER is the person your agents served (the user.id your SDK stamps), not a console login. Matched against ANY span of the trace, so a run counts if the user scope was open anywhere inside it. The column, though, is the ROOT span's user, so the two need not agree: a trace whose scope opened after its root matches the filter and still shows a BLANK cell. That gap is the any-span rule working as specified, not a filter that missed — read the trace's spans to see where the scope opened. anonymous: list the traffic carrying NO end user on any span, instead of one user's. A real subject rather than an error case: it is where un-instrumented traffic goes, and its error rate is worth knowing. The console's ?user=anonymous. Pass either user_id or anonymous, never both — they are disjoint by construction. filters: optional list of {"field": ..., "op": ..., "values": [...]} clauses, ANDed together and composable with the named parameters above. Cheapest first: status, agent, service, model, span_kind, operation, session_id are promoted columns and cost the same over any window. attr.<key> and resource.<key> reach a customer's own attributes and are ~10x dearer, so narrow with a column first; they are accepted only over windows of 31 days or less. Ops: eq, ne, in, not_in, gt, gte, lt, lte, exists, not_exists. Substring on an attribute value is refused — use error_text or search instead. Call describe_search_catalog before guessing a key; a rejected clause comes back naming itself. search: optional case-insensitive contains match on span name, span id, trace id, or session id. A session id alone — e.g. a coding-agent session's — finds every trace of that session in one call; on a core that predates session-id search it matches nothing, so fall back to filters=[{"field": "session_id", "op": "eq", "values": [...]}]. error_text: optional free text over the failure itself — the status message and any recorded exception. This is how you find a failure by what it said ("rate limit", "connection reset") rather than by where it was. limit: max rows (default 20). cursor: opaque page token from a previous call's next-page cursor, to fetch the page after it.

The sent_by column names the developer whose ingest key sent the trace (their stable email — a console-made key falls back to its creator's own email, so it usually carries one too). Blank only when the key could not be resolved (unknown, another workspace's, or a failed lookup), or the trace predates attribution.

Example:

Why did checkout-agent start failing at 14:00?

{
    "name": "list_agent_traces",
    "arguments": {
        "agent": "checkout-agent", "status": "Error", "root_status": "Error",
        "start": "2026-09-16T14:00:00Z", "end": "2026-09-16T15:00:00Z",
        "error_text": "rate limit"
    }
}

Failed runs that used gpt-4o and called the send_email tool.

{
    "name": "list_agent_traces",
    "arguments": {
        "status": "Error",
        "filters": [
            {"field": "model", "op": "eq", "values": ["gpt-4o"]},
            {"field": "attr.tool.name", "op": "eq", "values": ["send_email"]}
        ]
    }
}

Example:

Show me the failed runs from the last two days.

{ "name": "list_agent_traces", "arguments": { "hours": 48, "status": "Error" } }

Which runs actually failed, ignoring the ones that retried and recovered?

{ "name": "list_agent_traces", "arguments": { "hours": 48, "root_status": "Error" } }

Show me the runs that hit errors but finished cleanly anyway.

{
    "name": "list_agent_traces",
    "arguments": { "hours": 48, "status": "Error", "root_status": "Ok" }
}

checkout-agent's traces between two dates.

{
    "name": "list_agent_traces",
    "arguments": {
        "agent": "checkout-agent",
        "start": "2026-08-01T00:00:00Z",
        "end": "2026-08-08T00:00:00Z"
    }
}