> ## 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 a vector

> Search a namespace using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores.

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

<RequestExample>
  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="INDEX_HOST"

  curl "https://$INDEX_HOST/query" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "namespace": "example-namespace",
      "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
      "filter": {"genre": {"$eq": "documentary"}},
      "topK": 3,
      "includeValues": true
    }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /query
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:
  /query:
    post:
      tags:
        - Vector Operations
      summary: Search with a vector
      description: >-
        Search a namespace using a query vector. It retrieves the ids of the
        most similar items in a namespace, along with their similarity scores.


        For guidance, examples, and limits, see
        [Search](https://docs.pinecone.io/guides/search/search-overview).
      operationId: queryVectors
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
          links:
            FetchMatchedRecord:
              description: Look up a record returned as a query match.
              operationId: fetchVectors
              parameters:
                ids: $response.body#/matches/0/id
                namespace: $response.body#/namespace
            UpdateMatchedRecord:
              description: Update a record returned as a query match.
              operationId: updateVector
            DeleteMatchedRecord:
              description: Delete a record returned as a query match.
              operationId: deleteVectors
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '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/rpcStatus'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
components:
  schemas:
    QueryRequest:
      description: The request for the `query` operation.
      type: object
      properties:
        namespace:
          example: example-namespace
          description: The namespace to query.
          type: string
        topK:
          example: 10
          description: The number of results to return for each query.
          type: integer
          format: int64
          minimum: 1
          maximum: 10000
        filter:
          example:
            genre:
              $in:
                - comedy
                - documentary
                - drama
            year:
              $eq: 2019
          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
        includeValues:
          example: true
          description: >-
            Indicates whether vector values are included in the response. For
            on-demand indexes, setting this to `true` may increase latency,
            especially with higher `topK` values, because vector values are
            retrieved from object storage. Unless you need vector values, set
            this to `false` for better performance.
          default: false
          type: boolean
        includeMetadata:
          example: true
          description: >-
            Indicates whether metadata is included in the response as well as
            the ids.
          default: false
          type: boolean
        vector:
          example:
            - 0.1
            - 0.2
            - 0.3
            - 0.4
            - 0.5
            - 0.6
            - 0.7
            - 0.8
          description: >-
            The query vector. This should be the same length as the dimension of
            the index being queried. Each `query` request can contain only one
            of the parameters `id` or `vector`.


            Whether `vector` and `sparseVector` may be sent together depends on
            the index: an index that supports only a single query predicate
            rejects the combination.
          type: array
          items:
            type: number
            format: float
          minItems: 1
          maxItems: 20000
        sparseVector:
          $ref: '#/components/schemas/SparseValues'
        id:
          example: example-vector-1
          description: >-
            The unique ID of the vector to be used as a query vector. It is
            mutually exclusive with both vector forms: a request naming `id` may
            not also carry `vector` or `sparseVector`.
          type: string
          pattern: ^[\x01-\x7F]+$
          minLength: 1
          maxLength: 512
        scanFactor:
          example: 2
          description: >-
            An optimization parameter for IVF dense indexes in dedicated read
            node indexes. It adjusts how much of the index is scanned to find
            vector candidates. Range: 0.5 – 4 (default).

            Keep the default (4.0) for the best search results. If query latency
            is too high, try lowering this value incrementally (minimum 0.5) to
            speed up the search at the cost of slightly lower accuracy. This
            parameter is only supported for dedicated (DRN) dense indexes.
          type: number
          format: float
          minimum: 0.5
          maximum: 4
        maxCandidates:
          example: 1000
          description: >-
            An optimization parameter that controls the maximum number of
            candidate dense vectors to rerank. Reranking computes exact
            distances to improve recall but increases query latency. Range:
            top_k – 100000.

            Keep the default for a balance of recall and latency. Increase this
            value if recall is too low, or decrease it to reduce latency at the
            cost of accuracy. This parameter is only supported for dedicated
            (DRN) dense indexes.
          type: integer
          format: int64
          minimum: 1
          maximum: 100000
      required:
        - topK
      anyOf:
        - required:
            - vector
        - required:
            - id
        - required:
            - sparseVector
      not:
        anyOf:
          - required:
              - id
              - vector
          - required:
              - id
              - sparseVector
    QueryResponse:
      description: >-
        The response for the `query` operation. These are the matches found for
        a particular query vector. The matches are ordered from most similar to
        least similar.
      type: object
      properties:
        results:
          deprecated: true
          description: >-
            DEPRECATED. The results of each query. The order is the same as
            `QueryRequest.queries`.
          type: array
          items:
            $ref: '#/components/schemas/SingleQueryResults'
        matches:
          description: The matches for the vectors.
          type: array
          items:
            $ref: '#/components/schemas/ScoredVector'
        namespace:
          description: The namespace for the vectors.
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
    rpcStatus:
      description: >-
        The error response shape returned by the vector and bulk operations.
        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 instead.
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
    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
    SparseValues:
      description: >-
        Vector sparse data. Represented as a list of indices and a list of 
        corresponded values, which must be with the same length.
      type: object
      properties:
        indices:
          example:
            - 1
            - 312
            - 822
            - 14
            - 980
          description: The indices of the sparse data.
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
            maximum: 4294967295
          minItems: 1
          maxItems: 2048
        values:
          example:
            - 0.1
            - 0.2
            - 0.3
            - 0.4
            - 0.5
          description: >-
            The corresponding values of the sparse data, which must be with the
            same length as the indices.
          type: array
          items:
            type: number
            format: float
          minItems: 1
          maxItems: 2048
      required:
        - indices
        - values
    SingleQueryResults:
      title: The query results for a single query vector
      type: object
      properties:
        matches:
          description: The matches for the vectors.
          type: array
          items:
            $ref: '#/components/schemas/ScoredVector'
        namespace:
          example: example-namespace
          description: The namespace for the vectors.
          type: string
    ScoredVector:
      type: object
      properties:
        id:
          example: example-vector-1
          description: This is the vector's unique id.
          type: string
          minLength: 1
          maxLength: 512
        score:
          example: 0.08
          description: >-
            This is a measure of similarity between this vector and the query
            vector.  The higher the score, the more they are similar.
          type: number
          format: float
        values:
          example:
            - 0.1
            - 0.2
            - 0.3
            - 0.4
            - 0.5
            - 0.6
            - 0.7
            - 0.8
          description: This is the vector data, if it is requested.
          type: array
          items:
            type: number
            format: float
        sparseValues:
          $ref: '#/components/schemas/SparseValues'
        metadata:
          example:
            genre: documentary
            year: 2019
          description: This is the metadata, if it is requested.
          type: object
      required:
        - id
    Usage:
      type: object
      properties:
        readUnits:
          example: 5
          description: The number of read units consumed by this operation.
          type: integer
          format: int64
    protobufAny:
      type: object
      properties:
        typeUrl:
          type: string
        value:
          type: string
          format: byte
  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/).

````