Search API

REST API endpoints for vector similarity search, recommendations, and query operations in Qdrant

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)

Batch Search

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