Skip to main content
POST
/
vectors
/
fetch_by_metadata
# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
  -H 'Api-Key: $PINECONE_API_KEY' \
  -H 'Content-Type: application/json' \
  -H "X-Pinecone-API-Version: 2025-10" \
  -d '{
    "namespace": "example-namespace",
    "filter": {"rating": {"$lt": 5}},
    "limit": 2
  }'

{
  "vectors": {
    "id-1": {
      "id": "id-1",
      "values": [
        -0.0273742676,
        -0.000517368317,
        ...
      ],
      "metadata": {
        "main_category": "Books",
        "rating": 4,
        "review": "Identical twins have only one purpose in movies and plays: to cause mass confusion...",
        "title": "A comedy of twin-switching"
      }
    },
    "id-2": {
      "id": "id-2",
      "values": [
        -0.00305938721,
        0.0234375,
        ...
      ],
      "metadata": {
        "main_category": "Automotive",
        "rating": 1,
        "review": "If I could rate this 1/2 a star I would! These both broke within 10 minutes  of using it. The only upside is the cloth is removable so it can be used with good old fashioned  elbow grease. Epic waste!",
        "title": "Dont waste your money!"
      }
    }
  },
  "namespace": "example-namespace",
  "usage": {
    "readUnits": 1
  }
}

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/manage-data/target-an-index
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"

curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \
  -H 'Api-Key: $PINECONE_API_KEY' \
  -H 'Content-Type: application/json' \
  -H "X-Pinecone-API-Version: 2025-10" \
  -d '{
    "namespace": "example-namespace",
    "filter": {"rating": {"$lt": 5}},
    "limit": 2
  }'

{
  "vectors": {
    "id-1": {
      "id": "id-1",
      "values": [
        -0.0273742676,
        -0.000517368317,
        ...
      ],
      "metadata": {
        "main_category": "Books",
        "rating": 4,
        "review": "Identical twins have only one purpose in movies and plays: to cause mass confusion...",
        "title": "A comedy of twin-switching"
      }
    },
    "id-2": {
      "id": "id-2",
      "values": [
        -0.00305938721,
        0.0234375,
        ...
      ],
      "metadata": {
        "main_category": "Automotive",
        "rating": 1,
        "review": "If I could rate this 1/2 a star I would! These both broke within 10 minutes  of using it. The only upside is the cloth is removable so it can be used with good old fashioned  elbow grease. Epic waste!",
        "title": "Dont waste your money!"
      }
    }
  },
  "namespace": "example-namespace",
  "usage": {
    "readUnits": 1
  }
}

Authorizations

​
Api-Key
string
header
required

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

Headers

​
X-Pinecone-Api-Version
string
default:2025-10
required

Required date-based version header

Body

application/json

The request for the fetch_by_metadata operation.

​
namespace
string

The namespace to fetch vectors from.

Example:

"example-namespace"

​
filter
object

Metadata filter expression to select vectors. See Understanding metadata.

Example:
{
  "genre": { "$in": ["comedy", "documentary", "drama"] },
  "year": { "$eq": 2019 }
}
​
limit
integer
default:100

Max number of vectors to return.

Required range: x >= 1
Example:

12

​
paginationToken
string

Pagination token to continue a previous listing operation.

Example:

"Tm90aGluZyB0byBzZWUgaGVyZQo="

Response

A successful response.

The response for the fetch_by_metadata operation.

​
vectors
object

The fetched vectors, in the form of a map between the fetched ids and the fetched vectors

​
namespace
string
default:""

The namespace of the vectors.

Example:

"example-namespace"

​
usage
object
​
pagination
object