---
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

---

[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/fb597a4eaa56/schema)