---
title: "Get sanitized step-by-step execution trace for a test run"
method: GET
path: "/v1/test-runs/{test_run_id}/steps"
tags: ["test-runs"]
---

# Get sanitized step-by-step execution trace for a test run

`GET /v1/test-runs/{test_run_id}/steps`

Return the ordered list of user-facing actions the agent performed during
    a test run. Internal agent reasoning, supervisor bookkeeping, and raw
    screenshot/overlay artifacts are filtered out — this is the same subset
    the app.qualgent.ai test-run detail page renders as "steps".

    **Path Parameters:**
    - `test_run_id`: The unique identifier of the test run

    **Returns:**
    - Ordered array of step objects (`step_number`, `action`, `result`,
      `error_message`, `timestamp`).
    - Empty array if the run is queued/running with no steps recorded yet.

    **Authorization:**
    - Only returns steps for test runs belonging to your organization.

## Path parameters

- `test_run_id` string, required

## Headers

- `x-api-key` string

## Response `200`

Successfully retrieved test run steps

- TestRunStepItem[]
  - `step_number` integer, required — 1-indexed position of this step in the sanitized trace
  - `action` string, required — Human-readable description of what the agent did
  - `result` string, required — Outcome of the step
  - `error_message` string, nullable — Error text if the step failed; null otherwise.
  - `timestamp` string, required — ISO-8601 timestamp when the step was recorded.

## Other responses

- `401` — Invalid or missing API key
- `404` — Test run not found or doesn't belong to your organization
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) · [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qualgent/qualgent-api-service/revisions/2372ed4904a6/schema)