---
title: "Search Dataset Records"
method: POST
path: "/datasets/{dataset_id}/records/search"
tags: ["datasets"]
---

# Search Dataset Records

`POST /datasets/{dataset_id}/records/search`

## Path parameters

- `dataset_id` string, uuid, required

## Query parameters

- `offset` integer
- `limit` integer
- `include` string[], nullable

## Request body

- SearchRecordsQuery
  - `query` Query
    - `text` TextQuery
      - `q` string, required
      - `field` string, nullable
    - `vector` VectorQuery
      - `name` string, required
      - `record_id` string, uuid, nullable
      - `value` number[], nullable
      - `order` 'most_similar' | 'least_similar'
  - `filters` Filters
    - `and` union[], nullable
      - union
        - TermsFilter
          - `type` 'terms', required
          - `scope` union, required
            - RecordFilterScope
              - …
            - ResponseFilterScope
              - …
            - SuggestionFilterScope
              - …
            - MetadataFilterScope
              - …
          - `values` string[], required
        - RangeFilter
          - `type` 'range', required
          - `scope` union, required
            - RecordFilterScope
              - …
            - ResponseFilterScope
              - …
            - SuggestionFilterScope
              - …
            - MetadataFilterScope
              - …
          - `ge` union
            - number
            - string
          - `le` union
            - number
            - string
  - `sort` Order[], nullable
    - `scope` union, required
      - RecordFilterScope
        - `entity` 'record', required
        - `property` 'id' | 'external_id' | 'inserted_at' | 'updated_at' | 'status', required
      - ResponseFilterScope
        - `entity` 'response', required
        - `question` string, nullable — The name of the question
        - `property` 'status', nullable
      - SuggestionFilterScope
        - `entity` 'suggestion', required
        - `question` string, required — The name of the question
        - `property` 'value' | 'score' | 'agent' | 'type', nullable
      - MetadataFilterScope
        - `entity` 'metadata', required
        - `metadata_property` string, required
    - `order` 'asc' | 'desc', required

## Response `200`

Successful Response

- SearchRecordsResult
  - `items` SearchRecord[], required
    - `record` Record, required
      - `id` string, uuid, required
      - `status` 'pending' | 'completed', required
      - `fields` object, required
      - `metadata` object, nullable
      - `external_id` string, nullable
      - `reference` string, nullable
      - `responses` Response[], nullable
        - `id` string, uuid, required
        - `values` object, nullable
        - `status` 'draft' | 'submitted' | 'discarded', required
        - `record_id` string, uuid, required
        - `user_id` string, uuid, required
        - `inserted_at` string, date-time, required
        - `updated_at` string, date-time, required
      - `suggestions` Suggestion[], nullable
        - `question_id` string, uuid, required
        - `type` 'model' | 'human' | 'selection'
        - `value` unknown, required
        - `agent` string, nullable
        - `score` union
          - number
          - number[]
        - `id` string, uuid, required
        - `inserted_at` string, date-time, required
        - `updated_at` string, date-time, required
      - `vectors` object, nullable
      - `dataset_id` string, uuid, required
      - `inserted_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `query_score` number, nullable
  - `total` integer

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Content
- `500` — Internal Server Error

## Changes

- **2026-08-24** `ca32894f988c` — 17 breaking
  - removed the enum value `metadata` of the request property `filters/anyOf[subschema #1: Filters]/and/anyOf[subschema #1]/items/oneOf[subschema #1: TermsFilter]/scope/oneOf[subschema #4: MetadataFilterScope]/entity`
  - removed the enum value `metadata` of the request property `filters/anyOf[subschema #1: Filters]/and/anyOf[subschema #1]/items/oneOf[subschema #2: RangeFilter]/scope/oneOf[subschema #4: MetadataFilterScope]/entity`
  - removed the enum value `metadata` of the request property `sort/anyOf[subschema #1]/items/scope/oneOf[subschema #4: MetadataFilterScope]/entity`
  - removed the enum value `range` of the request property `filters/anyOf[subschema #1: Filters]/and/anyOf[subschema #1]/items/oneOf[subschema #2: RangeFilter]/type`
  - …13 more
- **2026-08-08** `e9da3a893a88` — 1 info
  - added the optional property `items/items/record/reference` to the response with the `200` status

[Change history](https://skmtc.dev/hf/apis/extralit-v1/changes/datasets/:dataset_id/records/search/post.md)

---

[API](https://skmtc.dev/hf/apis/extralit-v1.md) · [All operations](https://skmtc.dev/hf/apis/extralit-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hf/extralit-v1/revisions/ca32894f988c/schema)