Searching with text (`inputs`) is supported only for indexes with [integrated embedding](/guides/index-data-indexing-overview#vector-embedding); for any other index a text query is rejected with `400`, and it is not available on BYOC indexes; reranking (`rerank`) is likewise unavailable on BYOC indexes. Searching with a query vector (`vector`) or a record ID (`id`) works on any index served by the vectors API.

For guidance and examples, see [Search](/guides/index-data-search-search-overview).

:::code-group
```shell curl
INDEX_HOST="INDEX_HOST"
NAMESPACE="YOUR_NAMESPACE"
PINECONE_API_KEY="YOUR_API_KEY"

# Search with a query text and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
        "query": {
            "inputs": {"text": "Disease prevention"},
            "top_k": 4
        },
        "fields": ["category", "chunk_text"],
        "rerank": {
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"]
        }
     }'

# Search with a query vector and rerank the results
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
        "query": {
            "vector": {
                "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
            },
            "top_k": 4
        },
        "fields": ["category", "chunk_text"],
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"]
        }
     }'

# Search with a record ID and rerank the results
# Supported only for indexes with integrated embedding
curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "X-Pinecone-Api-Version: 2026-07" \
  -d '{
        "query": {
            "id": "rec1",
            "top_k": 4
        },
        "fields": ["category", "chunk_text"],
        "rerank": {
            "query": "Disease prevention",
            "model": "bge-reranker-v2-m3",
            "top_n": 2,
            "rank_fields": ["chunk_text"]
        }
     }'
```
:::

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

:::code-group
```json title="200"
{
  "namespace": "example-namespace",
  "result": {
    "hits": [
      {
        "_id": "example-record-1",
        "_score": 0.9281134605407715,
        "fields": {
          "data": "your example text"
        }
      }
    ]
  },
  "usage": {
    "egress_bytes": 1024,
    "embed_total_tokens": 10,
    "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 |
| --- | --- | --- | --- |
| `query` | `object` | - | . |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top_k` | `integer` | - | The number of similar records to return, from 1 to 10000. Required range: 1 <= x <= 10000. Example: 10 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `filter?` | `object` | - |  |

The filter to apply. You can use vector metadata to limit your search. See [Understanding metadata](/guides/index-data-indexing-overview#metadata).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `inputs?` | `object` | - |  |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `vector?` | `object` | - |  |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values?` | `number[]` | - | This is the vector data included in the request. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sparse_values?` | `number[]` | - | The sparse embedding values. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `sparse_indices?` | `integer[]` | - | The sparse embedding indices. |
:::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id?` | `string` | - | The unique ID of the vector to be used as a query vector. Required string length: 0 - 512. Example: example-vector-1 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `match_terms?` | `object` | - |  |

Specifies which terms must be present in the text of each search hit based on the specified strategy. The match is performed against the text field specified in the integrated index `field_map` configuration. Terms are normalized and tokenized into single tokens before matching, and order does not matter. Example: `"match_terms": {"terms": ["animal", "CHARACTER", "donald Duck"], "strategy": "all"}` will tokenize to `["animal", "character", "donald", "duck"]`, and would match `"Donald F. Duck is a funny animal character"` but would not match `"A duck is a funny animal"`. Match terms filtering is supported only for sparse indexes with [integrated embedding](/guides/index-data-indexing-overview#vector-embedding) configured to use the [pinecone-sparse-english-v0](/guides/more-models-pinecone-sparse-english-v0) model.

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strategy` | `string` | - | The strategy for matching terms in the text. Currently, only all is supported, which means all specified terms must be present. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `terms` | `string[]` | - | A list of terms that must be present in the text of each search hit based on the specified strategy. |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fields?` | `string[]` | - | The fields to return in the search results. If not specified, the response will include all fields. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rerank?` | `object` | - | Parameters for reranking the initial search results. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `model` | `string` | - | Example: bge-reranker-v2-m3 |

The name of the [reranking model](/guides/index-data-search-rerank-results#reranking-models) to use.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rank_fields` | `string[]` | - |  |

The field(s) to consider for reranking. Every returned record must contain each listed field; otherwise the request is rejected with `400`. The number of fields supported is [model-specific](/guides/index-data-search-rerank-results#reranking-models).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `top_n?` | `integer` | - | The number of top results to return after reranking. Defaults to top_k. Example: 5 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `parameters?` | `object` | - |  |

Additional model-specific parameters. Refer to the [model guide](/guides/index-data-search-rerank-results#reranking-models) for available model parameters.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query?` | `string` | - | The query to rerank documents against. If a specific rerank query is specified, it overwrites the query input that was provided at the top level. Required when the search uses vector or id, since there is no query text to rerank against; omitting it in that case is rejected with 400. Example: What is the capital of France? |
:::

#### Response

`200` — A successful search namespace response.

The records search response.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `result` | `object` | - |  |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hits` | `object[]` | - | The hits for the search document request. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `_id` | `string` | - | The record id of the search hit. Required string length: 1+ |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `_score` | `number` | - | The similarity score of the returned record. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` | `object` | - | The selected record fields associated with the search hit. |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | - |  |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `read_units` | `integer` | - | The number of read units consumed by this operation. Required range: 0 <= x. 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 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `embed_total_tokens?` | `integer` | - | The number of embedding tokens consumed by this operation. Required range: 0 <= x. Example: 2 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rerank_units?` | `integer` | - | The number of rerank units consumed by this operation. Required range: 0 <= x. Example: 1 |
:::

| 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: example-namespace |

## Related pages

- [Search with a vector](./database-data-plane-query.md)
- [Upsert records](./database-data-plane-upsert.md)
- [Upsert text](./database-data-plane-upsert-records.md)
- [Fetch records](./database-data-plane-fetch.md)
- [Fetch records by metadata](./database-data-plane-fetch-by-metadata.md)
- [Update a record](./database-data-plane-update.md)
- [Delete records](./database-data-plane-delete.md)
- [List record IDs](./database-data-plane-list.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.