Documentation menu
Agent Runs

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: createdAt or updatedAt.
  • order: asc or desc.

Pagination

  • limit: Number of Agent Runs to return (1–100, default 20).
  • cursor: Opaque cursor returned in pagination.nextCursor; reuse it only with the same filters and ordering.

Response

  • Returns agentRuns with canonical run ID, Agent and Agent Revision identity, actor, lifecycle state, digests, timestamps, runtime version, and content size.
  • Returns pagination with 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

NameTypeRequiredDescription
sort"createdAt" | "updatedAt"optionalSelects the resource field used to order results. Applies to List runs.
order"asc" | "desc"optionalSelects ascending or descending order for the requested sort field. Applies to List runs.
limitintegeroptionalSets the maximum number of resources returned in this page. Applies to List runs.
cursorstringoptionalOpaque cursor returned by the previous page; omit it to read the first page. Applies to List runs.
organizationIdstringoptionalSelects the organization that owns the collection. Required for session credentials. A credential scoped to one organization may omit it. Applies to List runs.
projectIdstringoptionalFilters results to the specified Project. Applies to List runs.
environmentIdstringoptionalSelects the active Project environment coordinate. Applies to List runs.
agentIdstringoptionalSelects the Project Agent by its stable identifier. Applies to List runs.
agentRunIdstringoptionalFilters runs to the single Agent Run with this identifier. Applies to List runs.
agentJobIdstringoptionalFilters runs to those created by this scheduled agent job. Applies to List runs.
createdBystringoptionalFilters runs to the specified creator identity. Applies to List runs.
statesarray<"queued" | "acquiring" | "starting" | "running" | "awaitingToolResult" | "awaitingDelegateResult" | "canceling" | "completed" | "failed" | "canceled" | "expired">optionalFilters runs to the supplied set of lifecycle states. Applies to List runs.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — agentRuns: array<AgentRun> (required); pagination: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)