Skip to main content
POST
/
v1
/
vectors
/
query
Query Vectors
curl --request POST \
  --url https://api.example.com/v1/vectors/query
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"]
}

​
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)
  • 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,
       "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 values and greedy=true increase recall but may reduce query performance. Start with default values and adjust based on your recall requirements.