> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search with text

> 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 (`inputs`) is supported only for indexes with [integrated embedding](https://docs.pinecone.io/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](https://docs.pinecone.io/guides/search/search-overview).

<RequestExample>
  ```shell curl theme={null}
  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"]
          }
       }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /records/namespaces/{namespace}/search
openapi: 3.0.3
info:
  title: Pinecone Data Plane API
  description: >-
    Pinecone is a vector database that makes it easy to search and retrieve
    billions of high-dimensional vectors.
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 2026-07
servers:
  - url: https://{index_host}
    variables:
      index_host:
        default: unknown
        description: host of the index
security:
  - ApiKeyAuth: []
tags:
  - name: Vector Operations
  - name: Bulk Operations
  - name: Namespace Operations
  - name: Document Operations
    description: >-
      Operations on documents in an index created with a document schema — one
      that declares at least one full-text-searchable string field or a
      `dense_vector` / `sparse_vector` field under a name other than the
      reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
      document schema. Indexes served by the vectors API — created from
      `dimension`/`metric` on an earlier API version, or from a schema holding
      only the reserved vector fields and metadata — and indexes served by the
      records API — created with an integrated embedding model, whose schema
      holds a single `semantic_text` field — reject every document operation
      with `400` and name the API to use instead. A document index accepts only
      the document operations; the vector data operations (upsert, query, fetch,
      update, delete, list) reject it, while index stats and the namespace
      operations remain available.
externalDocs:
  description: More Pinecone.io API docs
  url: https://docs.pinecone.io/introduction
paths:
  /records/namespaces/{namespace}/search:
    post:
      tags:
        - Vector Operations
      summary: Search with text
      description: >-
        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 (`inputs`) is supported only for indexes with
        [integrated
        embedding](https://docs.pinecone.io/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](https://docs.pinecone.io/guides/search/search-overview).
      operationId: searchRecordsNamespace
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            type: string
          style: simple
        - in: path
          name: namespace
          description: The namespace to search.
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRecordsRequest'
        required: true
      responses:
        '200':
          description: A successful search namespace response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRecordsResponse'
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. Possible causes: missing or invalid API key.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedMessage'
        4XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SearchRecordsRequest:
      example:
        fields:
          - chunk_text
        query:
          inputs:
            text: your query text
          top_k: 10
      description: A search request for records in a specific namespace.
      type: object
      properties:
        query:
          description: .
          type: object
          properties:
            top_k:
              example: 10
              description: The number of similar records to return, from 1 to 10000.
              type: integer
              format: int32
              minimum: 1
              maximum: 10000
            filter:
              description: >-
                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).
              type: object
            inputs:
              $ref: '#/components/schemas/EmbedInputs'
            vector:
              $ref: '#/components/schemas/SearchRecordsVector'
            id:
              example: example-vector-1
              description: The unique ID of the vector to be used as a query vector.
              type: string
              maxLength: 512
            match_terms:
              $ref: '#/components/schemas/SearchMatchTerms'
          required:
            - top_k
        fields:
          example:
            - chunk_text
          description: >-
            The fields to return in the search results. If not specified, the
            response will include all fields.
          type: array
          items:
            type: string
        rerank:
          description: Parameters for reranking the initial search results.
          type: object
          properties:
            model:
              example: bge-reranker-v2-m3
              description: >-
                The name of the [reranking
                model](https://docs.pinecone.io/guides/search/rerank-results#reranking-models)
                to use.
              type: string
            rank_fields:
              example:
                - chunk_text
                - title
              description: >
                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](https://docs.pinecone.io/guides/search/rerank-results#reranking-models).
              type: array
              items:
                type: string
            top_n:
              example: 5
              description: >-
                The number of top results to return after reranking. Defaults to
                top_k.
              type: integer
              format: int32
            parameters:
              example:
                truncate: END
              description: >-
                Additional model-specific parameters. Refer to the [model
                guide](https://docs.pinecone.io/guides/search/rerank-results#reranking-models)
                for available model parameters.
              type: object
              additionalProperties: true
            query:
              example: What is the capital of France?
              description: >-
                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`.
              type: string
          required:
            - model
            - rank_fields
      required:
        - query
    SearchRecordsResponse:
      example:
        result:
          hits:
            - _id: example-record-1
              _score: 0.9281134605407715
              fields:
                data: your example text
        usage:
          embed_total_tokens: 10
          read_units: 5
      description: The records search response.
      type: object
      properties:
        result:
          type: object
          properties:
            hits:
              description: The hits for the search document request.
              type: array
              items:
                $ref: '#/components/schemas/Hit'
          required:
            - hits
        usage:
          $ref: '#/components/schemas/SearchUsage'
      required:
        - usage
        - result
    ErrorResponse:
      example:
        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
      description: >-
        The error response shape returned by the records and documents
        operations. The vector operations return `rpcStatus` instead. Requests
        rejected by the authentication and rate-limiting layer before they reach
        the service (`401`, and the `400`, `403`, and `429` it produces) return
        a plain-text body on every operation.
      type: object
      properties:
        status:
          example: 400
          description: The HTTP status code of the error.
          type: integer
        error:
          description: Detailed information about the error that occurred.
          type: object
          properties:
            code:
              example: INVALID_ARGUMENT
              description: >-
                The error code.

                Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
                `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
                `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
                `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
                `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
                `PAYLOAD_TOO_LARGE`.
              x-enum:
                - OK
                - UNKNOWN
                - INVALID_ARGUMENT
                - DEADLINE_EXCEEDED
                - NOT_FOUND
                - ALREADY_EXISTS
                - PERMISSION_DENIED
                - UNAUTHENTICATED
                - RESOURCE_EXHAUSTED
                - FAILED_PRECONDITION
                - ABORTED
                - OUT_OF_RANGE
                - INTERNAL
                - FORBIDDEN
                - PAYMENT_REQUIRED
                - SERVICE_UNAVAILABLE
                - PAYLOAD_TOO_LARGE
              type: string
            message:
              example: >-
                No 'ids' or 'filter' provided in the document fetch request.
                Provide at least one document ID in 'ids', or a metadata filter
                in 'filter'.
              description: >-
                A human-readable description of the error, including how to
                correct the request where possible.
              type: string
          required:
            - code
            - message
      required:
        - status
        - error
    UnauthorizedMessage:
      example: Unauthorized
      description: >-
        The plain-text body of a `401` response. Authentication failures are
        rejected before the request reaches the index, so they carry the message
        `Unauthorized` rather than an error object.
      type: string
    EmbedInputs:
      example:
        text: chunk_text
      type: object
    SearchRecordsVector:
      type: object
      properties:
        values:
          $ref: '#/components/schemas/VectorValues'
        sparse_values:
          example:
            - 0.1
            - 0.2
            - 0.3
          description: The sparse embedding values.
          type: array
          items:
            type: number
            format: float
        sparse_indices:
          example:
            - 10
            - 3
            - 156
          description: The sparse embedding indices.
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
            maximum: 4294967295
    SearchMatchTerms:
      example:
        strategy: all
        terms:
          - animal
          - CHARACTER
          - donald Duck
      description: >-
        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.
      type: object
      properties:
        strategy:
          description: >-
            The strategy for matching terms in the text. Currently, only `all`
            is supported, which means all specified terms must be present.
          x-enum:
            - all
          type: string
        terms:
          description: >-
            A list of terms that must be present in the text of each search hit
            based on the specified strategy.
          type: array
          items:
            type: string
      required:
        - terms
        - strategy
    Hit:
      example:
        _id: example-record-1
        _score: 0.9281134605407715
        fields:
          data: your example text
          more_data:
            text: your example text
      description: A record whose vector values are similar to the provided search query.
      type: object
      properties:
        _id:
          description: The record id of the search hit.
          type: string
          minLength: 1
        _score:
          description: The similarity score of the returned record.
          type: number
          format: float
        fields:
          description: The selected record fields associated with the search hit.
          type: object
      required:
        - _id
        - _score
        - fields
    SearchUsage:
      type: object
      properties:
        read_units:
          example: 5
          description: The number of read units consumed by this operation.
          type: integer
          format: int32
          minimum: 0
        embed_total_tokens:
          example: 2
          description: The number of embedding tokens consumed by this operation.
          type: integer
          format: int32
          minimum: 0
        rerank_units:
          example: 1
          description: The number of rerank units consumed by this operation.
          type: integer
          format: int32
          minimum: 0
      required:
        - read_units
    VectorValues:
      description: This is the vector data included in the request.
      type: array
      items:
        type: number
        format: float
      minItems: 1
      maxItems: 20000
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: >-
        An API Key is required to call Pinecone APIs. Get yours from the
        [console](https://app.pinecone.io/).

````