---
title: "List a run's steps"
method: GET
path: "/runs/{run_id}/steps"
tags: ["Runs"]
---

# List a run's steps

`GET /runs/{run_id}/steps`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/runs/{run_id}/steps`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/runs/:run_id/steps/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists a run's model steps from its transcript, oldest first: the messages each step sent, the model's answer, links to its screenshots and its cost. Empty once the transcript has passed its retention, or when your organization keeps none.

## Path parameters

- `run_id` string, uuid, required: The run's id.

## Query parameters

- `cursor` string: The next_cursor of the page before; leave out for the first page.
- `limit` integer: Page size.

## Response `200`

OK

- AgentRunStepList: One page of an agent run's steps, oldest first. Empty once the run's transcript has passed its retention, or when the organization keeps none.
  - `next_cursor` string: Pass as cursor for the next page; absent on the last page.
  - `steps` AgentRunStep[], nullable, required: The steps on this page.
    - `compaction` AgentRunStepCompaction
      - `dropped_steps` integer, required: How many of the run's earlier steps were dropped from the conversation.
      - `note` string, required: What the model read in their place: what each dropped step did, and what people said in them.
    - `ended_at` string, date-time, required: When the step ended.
    - `error` string: Why the step failed, if it did.
    - `finish_reason` string: Why the model stopped.
    - `images` string[], nullable: Short-lived links to the step's screenshots, in the order messages refer to them.
    - `messages` unknown[], nullable, required: The messages the step added to the conversation, as the model received them. A message part refers to a screenshot by its index in images. A message a person sent the run while it worked is a user message with source "person" and message, the text as they sent it.
      - unknown
    - `model` string, required: The model that answered the step.
    - `response` unknown
    - `started_at` string, date-time, required: When the step started.
    - `step` integer, required: The step's number in the run, from 1.
    - `usage` AgentRunStepUsage: A model step's tokens and cost.
      - `cache_read_tokens` integer, required: Of the tokens sent, those read from the model provider's prompt cache, at the model's cache-read rate.
      - `cache_write_tokens` integer, required: Of the tokens sent, those written to the model provider's prompt cache, at the model's cache-write rate.
      - `completion_tokens` integer, required: Tokens the model answered with.
      - `cost_microdollars` integer, required: What the step cost, in microdollars.
      - `prompt_tokens` integer, required: Tokens the step sent, the cached ones included.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-11-02** `62aa324803a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/runs/:run_id/steps/get.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)