---
title: "List Test Runs"
method: GET
path: "/v1/agent/test-runs"
tags: ["Agent Tests"]
---

# List Test Runs

`GET /v1/agent/test-runs`

## Request

- Base URL: `https://api.fish.audio`
- URL: `https://api.fish.audio/v1/agent/test-runs`
- Auth: HTTP bearer

Your team's test runs, newest first, filtered by agent, test, batch,
status or test type. Items leave out the conversation and the judge's
output. Fetch one run with `GET /v1/agent/test-runs/{run_id}` for those.
Paginate with `cursor` (follow `next_cursor` while `has_more` is true) or
with `page` for offset pagination with a `total` count. The two are
mutually exclusive.

## Query parameters

- `agent_id` string, nullable
- `test_id` string, nullable
- `batch_id` string, nullable
- `status` 'queued' | 'running' | 'passed' | 'failed' | 'error', nullable
- `test_type` 'next_reply' | 'tool' | 'simulation', nullable
- `cursor` string, nullable
- `page` integer, nullable
- `include_total` boolean
- `page_size` integer

## Response `200`

Request fulfilled, document follows

- object
  - `runs` PublicAgentTestRunSummary[], required
    - `run_id` string, required
    - `test_id` string, required
    - `agent_id` string, required
    - `batch_id` string, nullable
    - `test_type` 'next_reply' | 'tool' | 'simulation', required
    - `repeat_index` integer: Which repeat of the test in its batch this run is.
    - `status` 'queued' | 'running' | 'passed' | 'failed' | 'error', required
    - `needs_review` boolean: The judge could not decide, or a tool call had no mock answer.
    - `error` string
    - `usage` PublicAgentTestRunUsage
      - `agent_replies` integer
      - `cost_usd` string, nullable: What the run was charged in USD. `0` on a finished run that is not charged: runs that end in `error` and tests other than simulations. Null until the run's charge is settled.
      - `platform_fee` PublicAgentTestRunPlatformFee
        - `rate_usd` string, required: USD per agent reply.
        - `amount_usd` string, required: `agent_replies` times `rate_usd`.
      - `llm` PublicAgentTestRunLLMCharge[]: LLM tokens, one entry per participant and model, by token category. With `platform_fee` they add up to `cost_usd`. Empty unless charged.
        - `participant` 'agent' | 'simulated_user' | 'judge', required: Whose tokens: the agent, the simulated user, or the judge.
        - `model` string, required
        - `amount_usd` string, required: What these tokens charged, in USD.
        - `input` PublicAgentTestRunTokenCharge
          - `tokens` integer, required
          - `amount_usd` string, required
        - `cache_read` PublicAgentTestRunTokenCharge
          - `tokens` integer, required
          - `amount_usd` string, required
        - `cache_write_5m` PublicAgentTestRunTokenCharge
          - `tokens` integer, required
          - `amount_usd` string, required
        - `cache_write_1h` PublicAgentTestRunTokenCharge
          - `tokens` integer, required
          - `amount_usd` string, required
        - `output` PublicAgentTestRunTokenCharge
          - `tokens` integer, required
          - `amount_usd` string, required
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable
    - `finished_at` string, date-time, nullable
  - `has_more` boolean, required
  - `next_cursor` string, nullable
  - `total` integer, nullable

## Other responses

- `400`: Bad request syntax or unsupported method
- `401`: No permission -- see authorization schemes
- `404`: Nothing matches the given URI
- `503`: The server cannot process the request due to a high load

## Changes

- **2026-11-03** `42ac421f7a12`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fish/apis/fishaudio-openapi/changes/v1/agent/test-runs/get.md)

---

[API](https://skmtc.dev/fish/apis/fishaudio-openapi.md) - [All operations](https://skmtc.dev/fish/apis/fishaudio-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/fish/apis/fishaudio-openapi/revisions/42ac421f7a12?raw)