Query Vectors

POST

vectors

query

Query Vectors

curl --request POST \
  --url https://api.example.com/v1/vectors/query

import requests

url = "https://api.example.com/v1/vectors/query"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/vectors/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/vectors/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/vectors/query"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/vectors/query")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/vectors/query")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Retrieve the nearest neighbors for a given query vector.

Authentication

Required - API key via X-API-Key header:

X-API-Key: cyborg_your_api_key_here

You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.

Request Body

Single Query Request

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "query_vectors": [0.1, 0.2, 0.3, 0.4],
  "top_k": 10,
  "n_probes": 1,
  "greedy": false,
  "filters": {"category": "greeting"},
  "include": ["distance", "metadata"]
}

Batch Query Request

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "query_vectors": [
    [0.1, 0.2, 0.3, 0.4],
    [0.5, 0.6, 0.7, 0.8]
  ],
  "top_k": 10,
  "n_probes": 1,
  "greedy": false,
  "filters": {"category": "greeting"},
  "include": ["distance", "metadata"]
}

Semantic Search Request (with embedding model)

{
  "index_name": "semantic_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "query_contents": "Find documents about machine learning",
  "top_k": 10,
  "filters": {"type": "research"},
  "include": ["distance", "metadata"]
}

Show parameters

index_name

string

required

Name of the target index

index_key

string

32-byte encryption key as a hex string. Required for indexes created with the SDK-supplied KEK path; omit for KMS-backed indexes (the service resolves the key via the stored KMSBlob).

query_vectors

array[number] | array[array[number]]

Query vector(s) for similarity search:

Single query: [0.1, 0.2, 0.3, ...] (1D array)
Batch query: [[0.1, 0.2, ...], [0.4, 0.5, ...]] (2D array) Required unless query_contents is provided

query_contents

string

Text content for semantic search (requires index with embedding_model). Alternative to query_vectors for automatic embedding generation

top_k

integer

default:100

Number of nearest neighbors to return

n_probes

integer

default:"auto"

Number of index lists to probe. When set to 0 or omitted, automatically determines optimal value based on index size and query requirements

greedy

boolean

default:"false"

Use greedy search for higher recall

rerank_mult

integer

default:10

Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns top_k * rerank_mult candidates before the rerank pass narrows the result down to top_k. Higher values trade query latency for recall. Ignored by indexes that do not rerank.

filters

object

MongoDB-style metadata filters

include

array[string]

default:[]

Fields to include in response. id is always returned. contents is not a valid value for query — to retrieve contents, call GET /v1/vectors/get (or the SDK’s get) with the matching IDs afterwards.

Show include options

distance

string

Include distance/similarity score to query vector

metadata

string

Include item metadata key-value pairs

vector

string

Include the stored rerank vector (returned at the index’s configured storage_precision)

Response

Single Query Response

When query_vectors is a 1D array or query_contents is used:

{
  "results": [
    {
      "id": "item_1",
      "distance": 0.123,
      "metadata": {"category": "greeting", "language": "en"}
    },
    {
      "id": "item_3",
      "distance": 0.245,
      "metadata": {"category": "greeting", "language": "es"}
    }
  ]
}

Batch Query Response

When query_vectors is a 2D array (array of arrays):

{
  "results": [
    [
      {"id": "item_1", "distance": 0.123, "metadata": {"category": "greeting"}},
      {"id": "item_2", "distance": 0.245, "metadata": {"category": "farewell"}}
    ],
    [
      {"id": "item_3", "distance": 0.156, "metadata": {"category": "question"}},
      {"id": "item_4", "distance": 0.298, "metadata": {"category": "answer"}}
    ]
  ]
}

The response format automatically matches the request format:

Single query → flat array of results
Batch query → nested array with results for each query

Metadata Filtering

Use MongoDB-style query operators:

{
  "filters": {
    "$and": [
      {"category": "greeting"},
      {"confidence": {"$gte": 0.9}}
    ]
  }
}

Supported operators: $and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

Exceptions

401: Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model
404: Index not found
422: Invalid request parameters or vector dimensions
500: Internal server error

Example Usage

Basic Query:

curl -X POST "http://localhost:8000/v1/vectors/query" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "query_vectors": [0.1, 0.2, 0.3, 0.4],
       "top_k": 5
     }'

With Filters:

curl -X POST "http://localhost:8000/v1/vectors/query" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "query_vectors": [0.1, 0.2, 0.3, 0.4],
       "top_k": 10,
       "filters": {
         "$and": [
           {"category": "document"},
           {"priority": {"$gte": 3}}
         ]
       },
       "include": ["distance", "metadata"]
     }'

Semantic Search:

# For indexes with embedding_model
curl -X POST "http://localhost:8000/v1/vectors/query" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "semantic_index",
       "index_key": "your_64_character_hex_key_here",
       "query_contents": "Find documents about machine learning",
       "top_k": 10,
       "filters": {"type": "research"}
     }'

Batch Query:

curl -X POST "http://localhost:8000/v1/vectors/query" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "query_vectors": [
         [0.1, 0.2, 0.3, 0.4],
         [0.5, 0.6, 0.7, 0.8],
         [0.9, 0.1, 0.2, 0.3]
       ],
       "top_k": 5,
       "include": ["distance"]
     }'

High Recall Query:

curl -X POST "http://localhost:8000/v1/vectors/query" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "query_vectors": [0.1, 0.2, 0.3, 0.4],
       "top_k": 20,
       "n_probes": 10,
       "rerank_mult": 20,
       "greedy": true
     }'

If embedding_model is configured for the index, you can use either query_vectors for direct vector search or query_contents for text-based semantic search.

Higher n_probes, rerank_mult, and greedy=true all increase recall but reduce query performance. Start with defaults and adjust based on your recall requirements.

Upsert Vectors (Binary)

Query Vectors (Binary)

⌘I

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

Authentication

Request Body

Single Query Request

Batch Query Request

Semantic Search Request (with embedding model)

Response

Single Query Response

Batch Query Response

Metadata Filtering

Exceptions

Example Usage

​Authentication

​Request Body

​Single Query Request

​Batch Query Request

​Semantic Search Request (with embedding model)

​Response

​Single Query Response

​Batch Query Response

​Metadata Filtering

​Exceptions

​Example Usage

Authentication

Request Body

Single Query Request

Batch Query Request

Semantic Search Request (with embedding model)

Response

Single Query Response

Batch Query Response

Metadata Filtering

Exceptions

Example Usage