Skip to main content
Qdrant provides powerful search capabilities including vector similarity search, recommendation systems, and flexible query APIs. These endpoints help you find similar vectors and implement semantic search.

​
Search Points

Retrieve the closest points based on vector similarity and optional filtering conditions. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/search' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "limit": 3
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to search in
Query Parameters
​
consistency
string
Read consistency level: majority, quorum, or all
​
timeout
integer
Request timeout in seconds
Request Body
​
vector
array | object
required
Vector to search for. Can be a dense vector array, sparse vector, or named vector.
​
limit
integer
Maximum number of results to return. Default is 10.
​
offset
integer
Offset for pagination. Default is 0.
​
filter
object
Filter conditions to apply
​
must
array
All conditions must match
​
should
array
At least one condition must match
​
must_not
array
All conditions must NOT match
​
params
object
Search parameters
​
hnsw_ef
integer
HNSW graph exploration factor. Higher values = more accurate but slower.
​
exact
boolean
If true, perform exact search instead of approximate
​
quantization
object
Quantization search parameters
​
score_threshold
float
Only return results with a score above this threshold
​
with_payload
boolean | array | object
Whether to return payload. Can be true, false, array of field names, or include/exclude object.
​
with_vector
boolean | array
Whether to return vectors. Can be true, false, or array of vector names.
Response
​
result
array
Array of scored points
​
id
integer | string
Point ID
​
score
float
Similarity score
​
payload
object
Point payload (if requested)
​
vector
array | object
Point vector (if requested)
Perform multiple search queries in a single request for better performance. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/search/batch' \
  -H 'Content-Type: application/json' \
  -d '{
    "searches": [
      {
        "vector": [0.2, 0.1, 0.9, 0.7],
        "limit": 3
      },
      {
        "vector": [0.5, 0.3, 0.2, 0.3],
        "limit": 3,
        "filter": {
          "must": [{"key": "city", "match": {"value": "London"}}]
        }
      }
    ]
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to search in
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
searches
array
required
Array of search requests. Each search has the same parameters as the single search endpoint.
Response
​
result
array
Array of result arrays, one for each search query

​
Search Groups

Search for points grouped by a specific payload field. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/search/groups' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "group_by": "city",
    "limit": 3,
    "group_size": 2
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to search in
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
vector
array | object
required
Vector to search for
​
group_by
string
required
Payload field to group results by
​
limit
integer
required
Maximum number of groups to return
​
group_size
integer
required
Maximum number of points per group
​
filter
object
Filter conditions
​
with_payload
boolean | array | object
Whether to return payload
​
with_vector
boolean | array
Whether to return vectors
​
with_lookup
object
Join payload from another collection
Response
​
result
object
​
groups
array
Array of groups
​
id
any
Group identifier (value of the group_by field)
​
hits
array
Points in this group

​
Recommend Points

Get recommendations based on positive and negative example points. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/recommend' \
  -H 'Content-Type: application/json' \
  -d '{
    "positive": [1, 2],
    "negative": [3],
    "limit": 5
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
positive
array
required
Array of point IDs or vectors to use as positive examples
​
negative
array
Array of point IDs or vectors to use as negative examples
​
limit
integer
Maximum number of results to return
​
offset
integer
Offset for pagination
​
filter
object
Filter conditions
​
using
string
Vector name to use for recommendation (for named vectors)
​
lookup_from
object
Lookup positive/negative examples from another collection
​
score_threshold
float
Minimum score threshold
​
with_payload
boolean | array | object
Whether to return payload
​
with_vector
boolean | array
Whether to return vectors
Response
​
result
array
Array of scored points with id, score, payload, and vector

​
Recommend Batch

Perform multiple recommendation queries in a single request. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/recommend/batch' \
  -H 'Content-Type: application/json' \
  -d '{
    "searches": [
      {
        "positive": [1, 2],
        "limit": 3
      },
      {
        "positive": [5, 6],
        "negative": [3],
        "limit": 5
      }
    ]
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
searches
array
required
Array of recommendation requests
Response
​
result
array
Array of result arrays, one for each recommendation query

​
Recommend Groups

Get recommendations grouped by a payload field. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/recommend/groups' \
  -H 'Content-Type: application/json' \
  -d '{
    "positive": [1, 2],
    "group_by": "category",
    "limit": 3,
    "group_size": 2
  }'
Parameters are similar to search groups, but with positive/negative examples instead of a query vector.

​
Query Points

Unified query API that supports multiple query types including nearest neighbors, discovery, and context-based search. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/query' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [0.2, 0.1, 0.9, 0.7],
    "limit": 10
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
query
array | object
required
Query specification. Can be:
  • Dense vector array for nearest neighbor search
  • Object with nearest for vector search
  • Object with recommend for recommendation
  • Object with discover for discovery search
  • Object with context for context-based search
  • Object with order_by for payload-based ordering
​
limit
integer
Maximum number of results
​
offset
integer
Offset for pagination
​
filter
object
Filter conditions
​
score_threshold
float
Minimum score threshold
​
with_payload
boolean | array | object
Whether to return payload
​
with_vector
boolean | array
Whether to return vectors
Response
​
result
object
​
points
array
Array of scored points

​
Query Batch

Perform multiple query operations in a single request. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/query/batch' \
  -H 'Content-Type: application/json' \
  -d '{
    "searches": [
      {
        "query": [0.2, 0.1, 0.9, 0.7],
        "limit": 3
      },
      {
        "query": {"recommend": {"positive": [1, 2]}},
        "limit": 5
      }
    ]
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
searches
array
required
Array of query requests
Response
​
result
array
Array of query results

​
Query Groups

Perform query operations with results grouped by a payload field. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/query/groups' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [0.2, 0.1, 0.9, 0.7],
    "group_by": "category",
    "limit": 3,
    "group_size": 2
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Query Parameters
​
consistency
string
Read consistency level
​
timeout
integer
Request timeout in seconds
Request Body
​
query
array | object
required
Query specification (same as query points)
​
group_by
string
required
Payload field to group by
​
limit
integer
required
Maximum number of groups
​
group_size
integer
required
Maximum points per group
​
filter
object
Filter conditions
​
with_payload
boolean | array | object
Whether to return payload
​
with_vector
boolean | array
Whether to return vectors
Response
​
result
object
​
groups
array
Array of groups with grouped query results

​
Search Matrix (Pairs)

Compute similarity scores between all pairs of points. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/search/matrix/pairs' \
  -H 'Content-Type: application/json' \
  -d '{
    "sample": 100,
    "limit": 10
  }'
Path Parameters
​
collection_name
string
required
Name of the collection
Request Body
​
sample
integer
Number of points to sample for matrix computation
​
limit
integer
Number of neighbors per point
​
filter
object
Filter to select points
Response
​
result
object
​
pairs
array
Array of point pairs with similarity scores

​
Search Matrix (Offsets)

Compute similarity matrix in offset format. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/search/matrix/offsets' \
  -H 'Content-Type: application/json' \
  -d '{
    "sample": 100,
    "limit": 10
  }'
Parameters are identical to search matrix pairs, but returns results in a compressed offset format suitable for large matrices.

​
Count Points

Count points in a collection that match a given filter. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/count' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "must": [
        {
          "key": "city",
          "match": {
            "value": "London"
          }
        }
      ]
    },
    "exact": true
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to count in
Query Parameters
​
consistency
string
Read consistency level: majority, quorum, or all
​
timeout
integer
Request timeout in seconds
Request Body
​
filter
object
Filter conditions to apply. Only points matching this filter will be counted.
​
exact
boolean
If true, provide exact count. If false, may provide approximate count for better performance.
Response
​
result
object
​
count
integer
Number of points matching the filter

​
Facet

Count points for each unique value of a payload key, optionally with filtering. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/facet' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "city",
    "limit": 10
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to facet in
Query Parameters
​
consistency
string
Read consistency level: majority, quorum, or all
​
timeout
integer
Request timeout in seconds
Request Body
​
key
string
required
Payload key to facet by
​
limit
integer
Maximum number of unique values to return. Default is 10.
​
filter
object
Filter conditions to apply before faceting
​
exact
boolean
If true, provide exact counts. If false, may use approximations for better performance.
Response
​
result
object
​
hits
array
Array of facet results
​
value
any
The unique value of the payload key
​
count
integer
Number of points with this value
Example: Count products by category 
curl -X POST 'http://localhost:6333/collections/products/facet' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "category",
    "limit": 20,
    "filter": {
      "must": [
        {
          "key": "in_stock",
          "match": { "value": true }
        }
      ]
    }
  }'

​
Discover Points

Look for points that satisfy context pairs (positive/negative examples) and optionally approach a target. 
curl -X POST 'http://localhost:6333/collections/{collection_name}/points/discover' \
  -H 'Content-Type: application/json' \
  -d '{
    "context": [
      {
        "positive": 100,
        "negative": 718
      },
      {
        "positive": 200,
        "negative": 300
      }
    ],
    "target": [0.2, 0.1, 0.9, 0.7],
    "limit": 10
  }'
Path Parameters
​
collection_name
string
required
Name of the collection to search in
Query Parameters
​
consistency
string
Read consistency level: majority, quorum, or all
​
timeout
integer
Request timeout in seconds
Request Body
​
context
array
Array of positive-negative example pairs. Each pair consists of a positive point ID and a negative point ID. Results will be points that are more similar to positives than negatives.
​
target
array | object
Optional target vector to approach. Can be a dense vector or named vector.
​
limit
integer
Maximum number of results to return. Default is 10.
​
filter
object
Filter conditions to apply
​
with_payload
boolean | array | object
Whether to return payload
​
with_vector
boolean | array
Whether to return vectors
Response
​
result
array
Array of scored points. The score combines context ranking and distance to target.
​
id
integer | string
Point ID
​
score
float
Combined score. Integer part represents context rank, decimal part represents distance to target.
​
payload
object
Point payload (if requested)
Use Case: Analogical Search Find items that have a similar relationship to the target as the positive/negative pairs demonstrate. 
# Find images similar to "night" as "day" is to "beach"
curl -X POST 'http://localhost:6333/collections/images/points/discover' \
  -H 'Content-Type: application/json' \
  -d '{
    "context": [
      {
        "positive": 1,  # "day" image
        "negative": 2   # "beach" image
      }
    ],
    "target": 3,  # "night" image
    "limit": 5
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us