List runs
GET /api/v1/agent-runs
List canonical Agent Runs accessible to the authenticated credential.
Scope
- Sessions must specify the organizationId query parameter. Credentials scoped to one Organization may omit it.
- Authorization is evaluated against the caller's Organization and Agent scope before pagination.
- A Project or Environment filter narrows the authorized run collection; it does not widen access.
- API keys and sessions use the same resource and operation authorization boundary.
Filtering
projectId: Optional canonical Project filter.environmentId: Optional canonical Environment filter.agentId: Optional canonical Agent filter.agentRunId: Optional exact Agent Run filter; combined with the other filters, it returns the run only when every filter matches.agentJobId: Optional scheduled Agent Job firing filter.createdBy: Optional creator identity filter.states: Optional lifecycle-state filter (comma-separated list or array).
Sorting
sort:createdAtorupdatedAt.order:ascordesc.
Pagination
limit: Number of Agent Runs to return (1–100, default 20).cursor: Opaque cursor returned inpagination.nextCursor; reuse it only with the same filters and ordering.
Response
- Returns
agentRunswith canonical run ID, Agent and Agent Revision identity, actor, lifecycle state, digests, timestamps, runtime version, and content size. - Returns
paginationwith the next opaque cursor when another page is available; no separate total-count field is returned.
Authentication
- Requires a valid session or API key in the Authorization header.
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
sort | "createdAt" | "updatedAt" | optional | Selects the resource field used to order results. Applies to List runs. |
order | "asc" | "desc" | optional | Selects ascending or descending order for the requested sort field. Applies to List runs. |
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List runs. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List runs. |
organizationId | string | optional | Selects the organization that owns the collection. Required for session credentials. A credential scoped to one organization may omit it. Applies to List runs. |
projectId | string | optional | Filters results to the specified Project. Applies to List runs. |
environmentId | string | optional | Selects the active Project environment coordinate. Applies to List runs. |
agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to List runs. |
agentRunId | string | optional | Filters runs to the single Agent Run with this identifier. Applies to List runs. |
agentJobId | string | optional | Filters runs to those created by this scheduled agent job. Applies to List runs. |
createdBy | string | optional | Filters runs to the specified creator identity. Applies to List runs. |
states | array<"queued" | "acquiring" | "starting" | "running" | "awaitingToolResult" | "awaitingDelegateResult" | "canceling" | "completed" | "failed" | "canceled" | "expired"> | optional | Filters runs to the supplied set of lifecycle states. Applies to List runs. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — agentRuns: array<AgentRun> (required); pagination: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |