Skip to main content
GET
List agent task runs
Returns the sub-agent tasks agents dispatched, newest first: who dispatched each and where (parentContextType is chat or workflow, with the run and node for a workflow), how the sub-agent was chosen (dispatchMode) and which agent ran it (resolvedAgentId), its status, timing, retries, steps and token usage.

Authority

You need agents:read at the platform scope; a grant only at an org unit answers a recorded 403. A row’s content (label, capabilityQuery, prompt, inputs, outputs, error) is returned only when its parent is a workflow run you can see (runs:read at the run’s home and at every company it carries). Otherwise those fields are null and contentWithheld is true; a chat-parented row always withholds them. Credential-shaped strings in shown content are replaced by [REDACTED]. Never the parent chat session, a worker id, a workpool job, the audit trail or the task’s tool sets.

Filtering

status is one of queued, running, completed, failed or cancelled.

Paging

Rows come newest first, a page at a time: limit is 1 to 100 (default 50; a larger value is 400 too_big). With status, foreground rows come before background rows, each newest first (the Console’s order), so an older foreground row can come ahead of a newer background one. While meta.hasMore is true, pass meta.nextCursor as cursor with the same status; the cursor starts d1. and is bound to this operation, status and the credential, and any other cursor answers 400 Invalid cursor. A row that names a Personal Agent is left out, so a page may hold fewer than limit rows while more remain. A row whose parent run cannot be decided within the request’s limits withholds its content, as a run you cannot see does. The list never answers meta.partial. An unavailable agent store answers 500, never an empty list.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

status
enum<string>

Only rows with this status.

Available options:
queued,
running,
completed,
failed,
cancelled
limit
integer
default:50

Items per page, 1 to 100 (default 50); a larger value is a 400 too_big. A page may hold fewer items than limit while meta.hasMore is true; continue with meta.nextCursor.

Required range: 1 <= x <= 100
cursor
string

The previous page's meta.nextCursor; any other value is 400.

Minimum string length: 1

Response

List agent task runs

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.