---
title: "Search with text"
method: POST
path: "/records/namespaces/{namespace}/search"
tags: ["Vector Operations"]
---

# Search with text

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

Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. 

Searching with text is supported only for indexes with [integrated embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding). Searching with a query vector or record ID is supported for all indexes. 

For guidance and examples, see [Search](https://docs.pinecone.io/guides/search/search-overview).

## Path parameters

- `namespace` string, required

## Headers

- `X-Pinecone-Api-Version` string, required

## Request body

- DbDataSearchRecordsRequest — A search request for records in a specific namespace.
  - `query` object, required — .
    - `top_k` integer, required — The number of similar records to return.
    - `filter` object — The filter to apply. You can use vector metadata to limit your search. See [Understanding metadata](https://docs.pinecone.io/guides/index-data/indexing-overview#metadata).
    - `inputs` DbDataEmbedInputs
    - `vector` DbDataSearchRecordsVector
      - `values` number[] — This is the vector data included in the request.
      - `sparse_values` number[] — The sparse embedding values.
      - `sparse_indices` integer[] — The sparse embedding indices.
    - `id` string — The unique ID of the vector to be used as a query vector.
    - `match_terms` DbDataSearchMatchTerms — 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](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) configured to use the [pinecone-sparse-english-v0](https://docs.pinecone.io/models/pinecone-sparse-english-v0) model.
      - `strategy` string — The strategy for matching terms in the text. Currently, only `all` is supported, which means all specified terms must be present.
      - `terms` string[] — A list of terms that must be present in the text of each search hit based on the specified strategy.
  - `fields` string[] — The fields to return in the search results. If not specified, the response will include all fields.
  - `rerank` object — Parameters for reranking the initial search results.
    - `model` string, required — The name of the [reranking model](https://docs.pinecone.io/guides/search/rerank-results#reranking-models) to use.
    - `rank_fields` string[], required — The field(s) to consider for reranking. If not provided, the default is `["text"]`. The number of fields supported is [model-specific](https://docs.pinecone.io/guides/search/rerank-results#reranking-models).
    - `top_n` integer — The number of top results to return after reranking. Defaults to top_k.
    - `parameters` object — Additional model-specific parameters. Refer to the [model guide](https://docs.pinecone.io/guides/search/rerank-results#reranking-models) for available model parameters.
    - `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.

## Response `200`

A successful search namespace response.

- DbDataSearchRecordsResponse — The records search response.
  - `result` object, required
    - `hits` DbDataHit[], required — The hits for the search document request.
      - `_id` string, required — The record id of the search hit.
      - `_score` number, float, required — The similarity score of the returned record.
      - `fields` object, required — The selected record fields associated with the search hit.
  - `usage` DbDataSearchUsage, required
    - `read_units` integer, required — The number of read units consumed by this operation.
    - `embed_total_tokens` integer — The number of embedding tokens consumed by this operation.
    - `rerank_units` integer — The number of rerank units consumed by this operation.

## Other responses

- `400` — Bad request. The request body included invalid request parameters.
- `4XX` — An unexpected error response.
- `5XX` — An unexpected error response.

---

[API](https://skmtc.net/pinecone/apis/pinecone-api.md) · [All operations](https://skmtc.net/pinecone/apis/pinecone-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinecone/pinecone-api/revisions/35876583485d/schema)