---
title: "Search experiment runs"
method: POST
path: "/v2/experiments/{experiment_id}/runs/search"
tags: ["Experiments"]
---

# Search experiment runs

`POST /v2/experiments/{experiment_id}/runs/search`

## Request

- Base URL: `https://api.arize.com`
- URL: `https://api.arize.com/v2/experiments/{experiment_id}/runs/search`
- Auth: HTTP bearer

Search runs for a given experiment with an optional SQL-like filter.

Runs are returned in stable `id` ascending order. Pagination uses the
cursor returned in `pagination.next_cursor`; keep the filter unchanged
when requesting subsequent pages.

The filter language supports the unprefixed run columns `id`, `output`,
`example_id`, custom run columns, `eval.<name>.score`,
`eval.<name>.label`, `eval.<name>.explanation`,
`eval.<name>.metadata.*`, and `annotation.<name>.*` when those columns
are present in the run schema.

**Payload Requirements**
- `filter` is optional. Omitting it returns all runs. A present empty or
  whitespace-only value is invalid.
- `limit` is optional and defaults to 50; valid values are 1 through 500.
- `cursor` is optional; omitting it starts at the first page.
- Unknown properties are rejected.

**Valid example**
```json
{
  "filter": "eval.quality.score < 0.5",
  "limit": 50,
  "cursor": "opaque-cursor"
}
```

**Invalid example** (limit is outside the supported range)
```json
{
  "filter": "output = 'approved'",
  "limit": 501
}
```

<Warning>This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>

## Path parameters

- `experiment_id` string, required: A universally unique identifier (base64-encoded opaque string).

## Request body

- SearchExperimentRunsRequest: Optional criteria for searching an experiment's runs. Omit all fields to return the first page of runs in stable `id` ascending order. Keep the filter unchanged when using a returned cursor to fetch the next page. Filters use the same SQL-like language as span search. Supported column families include unprefixed `id`, `output`, and `example_id`; custom run columns; `eval.<name>.score`, `eval.<name>.label`, `eval.<name>.explanation`, and `eval.<name>.metadata.*`; and `annotation.<name>.*` when present in the run schema. A present empty or whitespace-only filter is invalid.
  - `filter` string: SQL-like filter expression. Omit to search all runs; an empty or whitespace-only value is invalid.
  - `limit` integer: Maximum number of runs to return. Defaults to 50 and must be between 1 and 500.
  - `cursor` string: Opaque cursor from `pagination.next_cursor`. Omit to start at the first page; keep the filter unchanged while paging.

## Response `200`

Returns a list of experiment run objects

- ListExperimentRunsResponse
  - `experiment_runs` ExperimentRun[], required: Array of experiment run objects containing experiment fields and evaluations
    - `id` string, required: System-assigned unique ID for the example
    - `example_id` string, nullable: ID of the dataset example associated with this experiment run. Null when the experiment isn't associated with a dataset.
    - `output` string, nullable: Output of the task for the matching example. Null when the task errored.
    - `error` string, nullable: Error message when the task failed. Null on success.
    - `annotations` Annotation[]: List of human annotations on this experiment run
      - `name` string, required: The name of the annotation
      - `score` number, double: Numeric score for the annotation
      - `label` string: Categorical label for the annotation
      - `text` string: Free-form text note for the annotation
      - `updated_at` string, date-time: Timestamp when the annotation was last updated
      - `annotator` AnnotatorUser: A user assigned as an annotator, identified by ID and email.
        - `id` string, required: The unique identifier for the user
        - `email` string, email, required: An email address
  - `pagination` PaginationMetadata, required: Cursor-based pagination metadata. Use `next_cursor` in the subsequent request's `cursor` query parameter.
    - `next_cursor` string: Opaque cursor for fetching the next page. Treat as an unreadable token. Present when `has_more` is true; omitted when `has_more` is false.
    - `has_more` boolean, required: True if another page of results is available.

## Other responses

- `400`: Invalid request
- `401`: Authentication is required
- `403`: Insufficient permissions to access this resource
- `404`: Not found
- `422`: Unprocessable entity
- `429`: Rate limit exceeded

## Changes

> 48 revisions in range; 1 not diffed.

- **2026-09-26** `b235065883f9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/arize-ai/apis/arize-rest-api/changes/v2/experiments/:experiment_id/runs/search/post.md)

---

[API](https://skmtc.dev/arize-ai/apis/arize-rest-api.md) - [All operations](https://skmtc.dev/arize-ai/apis/arize-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/arize-ai/apis/arize-rest-api/revisions/22ad4acd3cbb?raw)