---
title: "Search"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Search

`POST /v1/search`

Perform a vector similarity search (VSS) operation on a dataset.

The search operation will return the most relevant matches based on cosine similarity with the input `text`.
The datasets queries should have an embedding column, and the appropriate embedding model loaded.

## Request body

- SearchRequestHTTPJson — HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls. `schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required. When the field is not required, the model ignores it.
  - `additional_columns` string[] — Additional columns to return from the dataset. If the column is a primary key, it will be returned within the response under `.primary_key`, not `.data`.
  - `datasets` string[], nullable — The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`.
  - `limit` integer, nullable — Number of documents to return for each dataset
  - `text` string, required — The text to search documents for similarity
  - `where` string, nullable — An SQL filter predicate to apply. Format: 'WHERE `where_cond`'.
  - `keywords` string[], nullable

## Response `200`

Search completed successfully

- SearchResponse
  - `duration_ms` integer, required — Total time taken to execute the search, in milliseconds
  - `results` Match[], required — List of matches that were found in the datasets
    - `_score` number, double, required — The similarity of the match to the query
    - `data` object — Addditional data from the `dataset` requested by the user.
    - `dataset` string, required — The name of the dataset where the match was found
    - `matches` object, required — The matches for this result
    - `metadata` object
    - `primary_key` object — Primary key(s) identifying the matched item in the dataset

## Other responses

- `400` — Invalid request parameters
- `500` — Internal server error

## Changes

- **2026-03-17** `934753ac3413` — 1 breaking, 1 info
  - removed the required property `results/items/score` from the response with the `200` status
  - added the required property `results/items/_score` to the response with the `200` status
- **2026-02-06** `c4d7063e0abe` — 1 breaking, 3 info
  - the `results/items/matches/additionalProperties/` response's property type/format changed from ``/`` to `array`/`` for status `200`
  - api tag `Search` added
  - api tag `SQL` removed
  - removed `subschema #1, subschema #2` from the `results/items/matches/additionalProperties/` response property `oneOf` list for the response status `200`
- **2025-06-02** `0f3e8eee80d3` — 1 breaking, 1 info
  - removed the required property `matches` from the response with the `200` status
  - added the required property `results` to the response with the `200` status
- **2025-03-18** `dd94571fef79` — 1 breaking, 3 info
  - removed the required property `results` from the response with the `200` status
  - api tag `SQL` added
  - api tag `Search` removed
  - added the required property `matches` to the response with the `200` status

[Change history](https://skmtc.dev/spiceai/apis/runtime/changes/v1/search/post.md)

---

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