POST
/
query
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: 2025-04" \
  -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
  }'

{
  "matches":[
    {
      "id": "vec3",
      "score": 0,
      "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
    },
    {
      "id": "vec2",
      "score": 0.0800000429,
      "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
    },
    {
      "id": "vec4",
      "score": 0.0799999237,
      "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
    }
  ],
  "namespace": "example-namespace",
  "usage": {"read_units": 6}
}

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: 2025-04" \
  -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
  }'

{
  "matches":[
    {
      "id": "vec3",
      "score": 0,
      "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
    },
    {
      "id": "vec2",
      "score": 0.0800000429,
      "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
    },
    {
      "id": "vec4",
      "score": 0.0799999237,
      "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
    }
  ],
  "namespace": "example-namespace",
  "usage": {"read_units": 6}
}

Authorizations

​
Api-Key
string
header
required

An API Key is required to call Pinecone APIs. Get yours from the console.

Body

application/json

The request for the query operation.

​
topK
integer
required

The number of results to return for each query.

Required range: 1 < x < 10000
​
namespace
string

The namespace to query.

​
filter
object

The filter to apply. You can use vector metadata to limit your search. See Understanding metadata.

​
includeValues
boolean
default:
false

Indicates whether vector values are included in the response.

​
includeMetadata
boolean
default:
false

Indicates whether metadata is included in the response as well as the ids.

​
queries
object[]
deprecated

DEPRECATED. Use vector or id instead.

​
vector
number[]

The query vector. This should be the same length as the dimension of the index being queried. Each request can contain either the id or vector parameter.

​
sparseVector
object

Vector sparse data. Represented as a list of indices and a list of corresponded values, which must be with the same length.

​
id
string

The unique ID of the vector to be used as a query vector. Each request can contain either the id or vector parameter.

Maximum length: 512

Response

200
application/json
A successful response.

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.

​
results
object[]
deprecated

DEPRECATED. The results of each query. The order is the same as QueryRequest.queries.

​
matches
object[]

The matches for the vectors.

​
namespace
string

The namespace for the vectors.

​
usage
object

Was this page helpful?

List vector IDsSearch with text