> ## Documentation Index > Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search dataset examples > 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..*` 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 } ``` This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages). ## OpenAPI ````yaml https://api.arize.com/v2/spec.yaml post /v2/datasets/{dataset_id}/examples/search openapi: 3.0.3 info: title: Arize REST API version: 2.0.0 description: | API specification for the backend data server. The API is hosted globally at https://api.arize.com/v2 or in your own environment. license: name: Apache-2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - description: Global url: https://api.arize.com - description: Regional url: https://api.{region}.arize.com variables: region: default: eu-west-1a enum: - eu-west-1a - ca-central-1a - description: Custom Host url: https://{host} variables: host: default: api.arize.com security: - bearerAuth: [] tags: - name: AI Integrations description: | AI integrations configure access to external LLM providers (e.g. OpenAI, Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the entire account, a specific organization, or a specific space. - name: Annotation Configs description: > Annotation configs allow you to define consistent annotation schemas that can be reused across your workspace, ensuring evaluations are structured and comparable over time. - name: Annotation Queues description: > Annotation queues help you organize and manage human evaluation workflows. Use queues to assign spans or examples to annotators for review and labeling. - name: API Keys description: > API keys are used to authenticate requests to the Arize API. List your keys to view metadata; the raw secret is never returned after creation. - name: Audit Logs description: > Audit logs record authenticated user actions within an account, providing a chronological trail for security and compliance review. Access requires account admin privileges and audit logging to be enabled. - name: Datasets description: | Datasets are structured, version-controlled example collections you use to run, evaluate, and track LLM experiments. - name: Evaluators description: > Evaluators are reusable evaluation configurations used to assess the quality of LLM outputs. They can be template-based (using LLM judges) or code-based. - name: Experiments description: > Experiments let you systematically test prompt/model changes using datasets, tasks, and evaluators. - name: Integrations description: > Integrations configure access to external LLM providers (e.g. OpenAI, Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g. PagerDuty, Slack), and your own agents. Integrations can be scoped to the entire account, a specific organization, or a specific space. - name: Monitors description: > Monitors continuously track a metric over your model or LLM application data and alert you when it crosses a threshold. Each monitor watches a single metric - data quality, model performance, drift, a custom metric, or a tracing metric - and moves between statuses as the metric passes in and out of its healthy range. - name: Organizations description: > Organizations are top-level containers within an Arize AX account for grouping spaces. - name: Projects description: | Projects represent LLM applications being monitored in Arize where you can observe traces and spans. - name: Prompts description: > Prompts are reusable, versioned templates for LLM interactions. Use prompts to standardize and manage how you interact with LLMs across your application. - name: Resource Restrictions description: | Endpoints for restricting and unrestricting resources (projects, models). - name: Role Bindings description: | Role bindings assign a role to a user on a resource. REST currently supports space- and project-scoped bindings. - name: Roles description: > Roles define sets of permissions that can be assigned to users within an account. Create custom roles to tailor access control to your team's needs. - name: Spaces description: > Spaces are containers within an organization for grouping related projects, datasets, and experiments, enabling collaboration or isolated experimentation with role-based access control. - name: Spans description: | Spans represent individual operations within a trace. A span captures the timing, status, and attributes of a single operation in your application. - name: Tags description: | Tags are reusable labels defined once per space and attached to resources across the platform, so the same vocabulary can be applied to projects, datasets, prompts, and more. Tags are shared: renaming or deleting a tag affects every resource it is attached to. - name: Tasks description: | Tasks are configurable units of work that tie one or more evaluators to a data source (project or dataset). Use tasks to automate evaluation of LLM outputs, with support for continuous evaluation and backfill runs. - name: Traces description: | A trace is the collection of spans sharing a trace ID, representing a single end-to-end request through an LLM application. Use the Traces endpoint to retrieve traces with all of their spans in one call. - name: Users description: > Users represent members of an account. The Users endpoints allow creating, listing, updating (display name), and removing users from the account programmatically. - name: Webhooks description: > Webhooks are organization-owned destinations that receive event deliveries over HTTPS. Deliveries are authenticated with a bearer token or signed with an HMAC signing secret — the secret is returned exactly once, when the webhook is created. Delivery attempts are recorded and can be listed for debugging. To choose which events a webhook receives, manage its subscriptions through the prompt and evaluator webhook-subscription endpoints. paths: /v2/datasets/{dataset_id}/examples/search: post: tags: - Datasets summary: Search dataset examples description: > 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..*` 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 } ``` This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages). operationId: search_dataset_examples parameters: - $ref: '#/components/parameters/DatasetIdPathParam' requestBody: $ref: '#/components/requestBodies/SearchDatasetExamplesRequestBody' responses: '200': $ref: '#/components/responses/ListDatasetExamplesResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimitExceeded' components: parameters: DatasetIdPathParam: name: dataset_id in: path description: The unique dataset identifier (base64) required: true schema: $ref: '#/components/schemas/Id' example: RGF0YXNldDoxMjM0NQ== requestBodies: SearchDatasetExamplesRequestBody: description: Body containing optional search criteria for dataset examples required: true content: application/json: schema: $ref: '#/components/schemas/SearchDatasetExamplesRequest' example: filter: topic = 'arithmetic' limit: 50 cursor: eyJjcmVhdGVkX2F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJpZCI6IjQifQ responses: ListDatasetExamplesResponse: description: Returns a list of dataset examples as structured objects content: application/json: schema: $ref: '#/components/schemas/ListDatasetExamplesResponse' example: examples: - id: 550e8400-e29b-41d4-a716-446655440000 created_at: '2024-01-01T12:00:00Z' updated_at: '2024-01-02T12:00:00Z' question: What is 2 + 2? answer: 4 topic: arithmetic isCorrect: true - id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 created_at: '2024-01-02T12:00:00Z' updated_at: '2024-01-03T12:00:00Z' question: What is the square root of 16? answer: 4 topic: geometry isCorrect: true - id: 9c7f6b2e-4a3d-11e9-8bad-f5b7b8c1ae7e created_at: '2024-01-03T12:00:00Z' updated_at: '2024-01-04T12:00:00Z' question: If 3x = 12, what is x? answer: 3 topic: algebra isCorrect: false pagination: next_cursor: cursor_12345 has_more: true BadRequest: description: Invalid request content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 400 title: Invalid request parameters detail: The 'name' field is required and must be a non-empty string. instance: /resource type: https://arize.com/docs/ax/rest-reference/errors#invalid-request Unauthorized: description: Authentication is required content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 401 title: Authentication required detail: You must be authenticated to access this resource. instance: /resource type: >- https://arize.com/docs/ax/rest-reference/errors#authentication-required Forbidden: description: Insufficient permissions to access this resource content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 403 title: Access forbidden detail: You do not have permission to access this resource. instance: /resource/12345 type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden NotFound: description: Not found content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 404 title: Resource not found detail: The requested resource with ID '12345' was not found. instance: /resource/12345 type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found UnprocessableEntity: description: Unprocessable entity content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 422 title: Unprocessable Entity detail: One or more fields failed validation. instance: /resource/12345 type: >- https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity RateLimitExceeded: description: Rate limit exceeded headers: Retry-After: description: | When throttled (429), how long to wait before retrying. Value is either a delta-seconds integer. schema: type: integer minimum: 0 example: 42 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 429 title: Rate limit exceeded detail: >- You have exceeded the allowed number of requests. Please try again later. instance: /resource type: >- https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded schemas: Id: type: string description: A universally unique identifier (base64-encoded opaque string). example: RW50aXR5OjEyMzQ1 SearchDatasetExamplesRequest: type: object description: > 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..*` when present in the example schema. A present empty or whitespace-only filter is invalid. properties: filter: type: string description: >- SQL-like filter expression. Omit to search all examples; an empty or whitespace-only value is invalid. example: topic = 'arithmetic' limit: type: integer format: int32 minimum: 1 maximum: 500 description: >- Maximum number of examples to return. Defaults to 50 and must be between 1 and 500. example: 50 cursor: type: string description: >- Opaque cursor from `pagination.next_cursor`. Omit to start at the first page; keep the filter unchanged while paging. example: opaque-cursor dataset_version_id: type: string description: >- Unique identifier of the dataset version to search. If omitted, the latest version is selected. example: RGF0YXNldFZlcnNpb246MTIzNDU= additionalProperties: false ListDatasetExamplesResponse: type: object required: - examples - pagination properties: examples: type: array items: $ref: '#/components/schemas/DatasetExample' description: Array of example objects from the dataset pagination: $ref: '#/components/schemas/PaginationMetadata' description: Pagination metadata for cursor-based navigation additionalProperties: false x-forward-compatible: true Problem: type: object description: RFC 9457 Problem Details properties: title: type: string description: A short, human-readable summary of the problem type status: type: integer description: >- The HTTP status code generated by the origin server for this occurrence of the problem type: type: string format: uri-reference description: A URI reference that identifies the problem type detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri-reference description: >- A URI reference that identifies the specific occurrence of the problem required: - title - status additionalProperties: false x-forward-compatible: true DatasetExample: type: object description: | A dataset example with arbitrary user-defined fields. System-managed fields are included as read-only for responses. properties: id: type: string description: System-assigned unique ID for the example readOnly: true created_at: type: string format: date-time description: Timestamp for when the example was created readOnly: true updated_at: type: string format: date-time description: Timestamp for the last update of the example readOnly: true annotations: type: array items: $ref: '#/components/schemas/Annotation' description: List of human annotations on this dataset example readOnly: true required: - id - created_at - updated_at additionalProperties: true PaginationMetadata: required: - has_more type: object properties: next_cursor: type: string description: > 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: type: boolean description: True if another page of results is available. description: | Cursor-based pagination metadata. Use `next_cursor` in the subsequent request's `cursor` query parameter. additionalProperties: false x-forward-compatible: true Annotation: type: object description: A human annotation on a record. required: - name properties: name: type: string description: The name of the annotation score: type: number format: double description: Numeric score for the annotation label: type: string description: Categorical label for the annotation text: type: string description: Free-form text note for the annotation updated_at: type: string format: date-time description: Timestamp when the annotation was last updated annotator: allOf: - $ref: '#/components/schemas/AnnotatorUser' description: The user who made this annotation additionalProperties: false x-forward-compatible: true AnnotatorUser: type: object description: A user assigned as an annotator, identified by ID and email. required: - id - email properties: id: type: string description: The unique identifier for the user email: $ref: '#/components/schemas/Email' additionalProperties: false x-forward-compatible: true Email: type: string format: email description: An email address example: user@example.com securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: description: > Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format ``` Authorization: Bearer ``` ````