---
title: "Search dataset examples"
method: POST
path: "/v2/datasets/{dataset_id}/examples/search"
tags: ["Datasets"]
---

# Search dataset examples

`POST /v2/datasets/{dataset_id}/examples/search`

## Request

- Base URL: `https://api.arize.com`
- URL: `https://api.arize.com/v2/datasets/{dataset_id}/examples/search`
- Auth: HTTP bearer

Search examples for a given dataset with an optional SQL-like filter.

Examples are returned in ascending order of `created_at`, with `id` as a
tiebreaker. This order is stable across pages. Pagination uses the
cursor returned in `pagination.next_cursor`; keep the filter unchanged
when requesting subsequent pages.

The filter language supports unprefixed example columns, `id`, and
`annotation.<name>.*` when those columns are present in the example
schema.

**Payload Requirements**
- `filter` is optional. Omitting it returns all examples. 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.
- `dataset_version_id` is optional; omitting it searches the latest
  version.

**Valid example**
```json
{
  "filter": "topic = 'arithmetic'",
  "limit": 50,
  "cursor": "opaque-cursor"
}
```

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

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

## Path parameters

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

## Request body

- SearchDatasetExamplesRequest: Optional criteria for searching a dataset's examples. Omit all fields to return the first page of examples in ascending order of `created_at`, with `id` as a tiebreaker. 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 example columns, `id`, and `annotation.<name>.*` when present in the example schema. A present empty or whitespace-only filter is invalid.
  - `filter` string: SQL-like filter expression. Omit to search all examples; an empty or whitespace-only value is invalid.
  - `limit` integer: Maximum number of examples 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.
  - `dataset_version_id` string: Unique identifier of the dataset version to search. If omitted, the latest version is selected.

## Response `200`

Returns a list of dataset examples as structured objects

- ListDatasetExamplesResponse
  - `examples` DatasetExample[], required: Array of example objects from the dataset
    - `id` string, required: System-assigned unique ID for the example
    - `created_at` string, date-time, required: Timestamp for when the example was created
    - `updated_at` string, date-time, required: Timestamp for the last update of the example
    - `annotations` Annotation[]: List of human annotations on this dataset example
      - `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-29** `b105f15d1dcd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/arize-ai/apis/arize-rest-api/changes/v2/datasets/:dataset_id/examples/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)