Documentation menu
Agent Runs

List steps

GET /api/v1/agent-runs/{agentRunId}/steps

List all agent steps for a specific run.

Sorting

  • sort: Sort by createdAt or updatedAt
  • order: Sort order (asc or desc)

Pagination

  • limit: Number of results to return (1-100, default 20)
  • cursor: Opaque cursor returned in pagination.nextCursor.

Depth

  • depth: Tree depth for nested step responses (0-10, default 0)
  • 0: Flat list of all steps (default)
  • 1: Root steps only (parentAgentStepId is null) with lastCheckpointId and empty childAgentSteps
  • 2+: Root steps with nested childAgentSteps up to the specified depth

Response

  • Returns steps with full details
  • Each step includes agent information and execution context
  • pagination.count is the number of steps in this page

Authentication

  • Requires a valid session or API key in the Authorization header

Parameters

path

NameTypeRequiredDescription
agentRunIdstringrequiredIdentifies the agent run whose state or history is addressed. Applies to List steps.

query

NameTypeRequiredDescription
sort"createdAt" | "updatedAt"optionalSelects the resource field used to order results. Applies to List steps.
order"asc" | "desc"optionalSelects ascending or descending order for the requested sort field. Applies to List steps.
limitintegeroptionalSets the maximum number of resources returned in this page. Applies to List steps.
cursorstringoptionalOpaque cursor returned by the previous page; omit it to read the first page. Applies to List steps.
depthintegeroptionalLimits step expansion to the requested nesting depth. Applies to List steps.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — agentSteps: array<AgentStepTreeNode> (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)