---
title: "Vector similarity search"
method: POST
path: "/api/v1/query"
---

# Vector similarity search

`POST /api/v1/query`

## Request

- Base URL: `https://api.vectorpanda.com`
- URL: `https://api.vectorpanda.com/api/v1/query`
- Auth: HTTP bearer

Search a collection by vector similarity. Returns the top-k most
similar vectors, optionally with metadata.

## Request body

- QueryRequest
  - `collection` string, required: Collection name
  - `vector` number[], required: Query vector (must match collection dimension)
  - `top_k` integer: Maximum number of results to return
  - `similarity_threshold` number, float: Minimum similarity score to include in results
  - `distance_metric` 'cosine' | 'euclidean' | 'dot_product'
  - `include_metadata` boolean: Include metadata fields in results
  - `use_index` 'pca' | 'none': Index strategy override (default chosen automatically)
  - `filter` object: MongoDB-style metadata filter. Only results whose metadata passes all conditions are returned. Operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin. Logical: $and, $or. Shorthand: {"field": "value"} means {"field": {"$eq": "value"}}. Multiple top-level keys are implicitly $and.

## Response `200`

Search results

- QueryResponse
  - `results` QueryResult[]
    - `key` string: Vector key (u128 decimal string)
    - `score` number, float: Similarity score
    - `metadata` object: Metadata fields (only present when include_metadata=true)
  - `worker_stats` WorkerStats[]
    - `worker_id` string
    - `search_time_ms` integer
    - `vectors_scanned` integer

## Other responses

- `401`: Invalid or missing API key
- `503`: No workers available for collection

---

[API](https://skmtc.dev/vectorpanda/apis/vector-panda-api.md) · [All operations](https://skmtc.dev/vectorpanda/apis/vector-panda-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vectorpanda/apis/vector-panda-api/revisions/f5fc74e883d4?raw)