Returns the top-k most similar documents along with their scores and requested fields.

A request includes a `score_by` array selecting one of the following scoring types:

- **`type: "text"`**, BM25 token matching over one or more text fields named in `fields`; naming several scores the query against all of them. Multi-word queries use OR-style matching (case-insensitive). For exact-phrase ranking, use `query_string` with quoted terms.
- **`type: "query_string"`**, Lucene query syntax. Supports boolean operators, phrase prefix matching, boosting, fuzzy matching (`term~`, `term~N`), and cross-field queries. See the [query syntax reference](/guides/index-data-search-full-text-search-query-syntax). **Does not accept a `field` or `fields` parameter.** Target specific fields using Lucene field qualifiers in the query string itself: `fieldname:value` or `title:(alpha) OR body:(beta)`.
- **`type: "dense_vector"`**, dense vector similarity ranking against a `dense_vector` field.
- **`type: "sparse_vector"`**, sparse vector similarity ranking against a `sparse_vector` field.

Any scoring method can be combined with metadata filters (including text match operators `$match_phrase` / `$match_all` / `$match_any` and logical operators `$and` / `$or` / `$not`). Filters are applied **before** scoring: the search only considers documents that match the filter. Scoring-only operators are available in `query_string` scoring but cannot be used inside `filter`: phrase slop (`"phrase"~N`), term boosting (`^N`), and phrase prefix (`"phrase pre"*`).

`include_fields` defaults to `[]` (returns only `_id` and `_score`); use `["*"]` to return all stored fields.

:::callout{intent="note"}
A single search request ranks by one scoring type. Multi-field BM25 is supported: name several fields in one `text` clause's `fields` array, or pass multiple `text` clauses, which the server combines into one ranking; a `query_string` clause can also target several fields. Every contributing field weighs equally in `2026-07`; there is no per-field weight parameter. To combine BM25 ranking with `dense_vector` or `sparse_vector` ranking, restrict the dense (or sparse) search with a text-match filter (`$match_phrase`, `$match_all`, `$match_any`) on the full-text field, or run separate searches and merge the results client-side.
:::

:::callout{intent="warning"}
Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are supported on this endpoint and on [fetch](/guides/database-data-plane-fetch-documents). A filtered [update](/guides/database-data-plane-update-documents) or [delete](/guides/database-data-plane-delete-documents) rejects them with a `400` and accepts plain metadata filters only. To update or delete by text match, search or fetch for the matching IDs first, then act on those IDs.
:::

:::code-group
```python Python
# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
index = pc.Index(name="articles")

NAMESPACE = "example-namespace"

# BM25 token matching
response = index.documents.search(
    namespace=NAMESPACE,
    top_k=10,
    score_by=[{"type": "text", "fields": ["body"], "query": "machine learning"}],
    include_fields=["title", "body", "category", "year"],
)
for match in response.matches:
    print(match._id, match._score, getattr(match, "title", ""))

# Lucene query string
response = index.documents.search(
    namespace=NAMESPACE,
    top_k=10,
    score_by=[{"type": "query_string", "query": "title:(quantum) OR body:(machine learning)"}],
    include_fields=["title", "body"],
)

# Dense vector ranking with phrase-match filter
query_vector = [0.12, 0.34, 0.56]  # replace with your actual query vector
response = index.documents.search(
    namespace=NAMESPACE,
    top_k=10,
    score_by=[{
        "type": "dense_vector",
        "fields": ["embedding"],
        "values": query_vector,
    }],
    filter={"body": {"$match_phrase": "machine learning"}},
    include_fields=["title", "body"],
)
```

```shell curl
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"

# EXAMPLE REQUEST 1: BM25 token matching (type: "text")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "include_fields": ["title", "body", "category", "year"],
    "score_by": [{
      "type": "text",
      "fields": ["body"],
      "query": "machine learning"
    }],
    "top_k": 10
  }'

# EXAMPLE REQUEST 2: Cross-field boolean query (type: "query_string")
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "include_fields": ["title", "body"],
    "score_by": [{
      "type": "query_string",
      "query": "title:(quantum) OR body:(machine learning)"
    }],
    "top_k": 10
  }'

# EXAMPLE REQUEST 3: Dense vector ranking with phrase-match filter
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "include_fields": ["title", "body"],
    "filter": { "body": { "$match_phrase": "machine learning" } },
    "score_by": [{
      "type": "dense_vector",
      "fields": ["embedding"],
      "values": [0.12, 0.34, 0.56]
    }],
    "top_k": 10
  }'

# EXAMPLE REQUEST 4: Sparse vector ranking
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "include_fields": ["title", "body"],
    "score_by": [{
      "type": "sparse_vector",
      "fields": ["sparse_embedding"],
      "sparse_values": {
        "indices": [12, 287, 4096],
        "values": [0.41, 0.33, 0.18]
      }
    }],
    "top_k": 10
  }'

# EXAMPLE REQUEST 5: Compound filter ($and + $match_all + metadata)
curl "https://$INDEX_HOST/namespaces/__default__/documents/search" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
    "include_fields": ["body", "category", "year"],
    "filter": {
      "$and": [
        { "body": { "$match_all": "federal reserve" } },
        { "category": { "$eq": "finance" } },
        { "year": { "$gte": 2024 } }
      ]
    },
    "score_by": [{
      "type": "text",
      "fields": ["body"],
      "query": "monetary policy impact"
    }],
    "top_k": 10
  }'
```
:::

`POST /namespaces/{namespace}/documents/search`

:::code-group
```json title="200"
{
  "matches": [
    {
      "_id": "doc-1",
      "_score": 0.9281134605407715,
      "title": "Introduction to Machine Learning"
    }
  ],
  "namespace": "my-namespace",
  "usage": {
    "egress_bytes": 1024,
    "read_units": 5
  }
}
```

```json title="400"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
```

```json title="4XX"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
```

```json title="5XX"
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "No 'ids' or 'filter' provided in the document fetch request. Provide at least one document ID in 'ids', or a metadata filter in 'filter'."
  },
  "status": 400
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Path Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | - | The namespace to search. |

#### Body

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `score_by` | `any` | - |  |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top_k` | `integer` | - | The number of top-ranked documents to return. Required range: 1 <= x <= 10000. Example: 10 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `include_fields?` | `string[]` | - | The document fields to return on each match alongside _id and _score. When omitted or empty, no fields are returned. Pass ['*'] to return every field. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filter?` | `object` | - | A metadata filter expression to restrict the documents searched. |

#### Response

`200` — A successful search response.

The response for the `search_documents` operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `matches` | `object[]` | - | The matching documents, ordered from most to least similar. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `_id` | `string` | - | The unique identifier of the matched document. Required string length: 1+ |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `_score` | `number \| null` | - | The similarity score of the matched document. null when the score is not a finite number, which can happen for dense vectors of very large magnitude. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `namespace` | `string` | - | The namespace that served the search: the request's namespace, or the alias's target namespace when the request named a namespace alias. Example: my-namespace |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - | Usage information for the search_documents operation. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `read_units` | `integer` | - | The number of read units consumed by this operation. Example: 5 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `egress_bytes?` | `integer` | - | The billed egress for this response, in bytes. Measured on the encoded response payload. Required range: 0 <= x. Example: 1024 |
:::

## Related pages

- [Upsert documents](./database-data-plane-upsert-documents.md)
- [Fetch documents](./database-data-plane-fetch-documents.md)
- [List documents](./database-data-plane-list-documents.md)
- [Update documents](./database-data-plane-update-documents.md)
- [Delete documents](./database-data-plane-delete-documents.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.