List namespace aliases
List the namespace aliases in a serverless index, ordered by name. Filter by name prefix or by target namespace.
Up to 100 aliases are returned per page; set limit to return fewer. When more remain, the response includes pagination.next; pass it as paginationToken to get the next page.
For guidance and examples, see Manage namespace aliases.
# 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 "https://$INDEX_HOST/namespace-aliases" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07"GET /namespace-aliases
{
"namespace_aliases": [
{
"name": "dataset",
"target_namespace": "dataset_v1",
"created_at": "2026-09-01T12:00:00.000Z",
"updated_at": "2026-09-01T12:00:00.000Z"
}
],
"pagination": {
"next": "Tm90aGluZyB0byBzZWUgaGVyZQo="
},
"total_count": 3
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"typeUrl": "<string>",
"value": "<string>"
}
]
}Authorizations
Section titled “Authorizations”Api-KeystringrequiredAn API Key is required to call Pinecone APIs. Get yours from the console.
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Query Parameters
Section titled “Query Parameters”limit?integerMax number of aliases to return per page. Defaults to 100.
Required range: 1 <= x <= 100
paginationToken?stringPagination token to continue a previous listing operation. Filters are carried by the token; if they are repeated in the request, they must match.
prefix?stringPrefix of the aliases to list. Acts as a filter to return only aliases whose name starts with this prefix.
Required string length: 0 - 512
target_namespace?stringReturn only aliases that resolve to this namespace. Use __default__ for the default namespace. Aliases cannot be targets, so an alias name here matches nothing. Combines with prefix.
Required string length: 1 - 512
Response
Section titled “Response”200 — A successful response
namespace_aliases?object[]The aliases in this index that match the request, ordered by name.
Show child attributes
namestringrequiredThe name of the alias. Immutable after creation.
Example: dataset
target_namespacestringrequiredThe namespace the alias resolves to. Changed only by repointing the alias. The default namespace is represented as __default__.
Example: dataset_v1
created_atstringrequiredThe time the alias was created.
Example: 2026-09-01T12:00:00.000Z
updated_atstringrequiredThe time the alias was last repointed. Advances on every repoint, including a repoint to the alias's current target; equals created_at until the first repoint.
Example: 2026-09-01T12:00:00.000Z
pagination?objectShow child attributes
nextstringrequiredExample: Tm90aGluZyB0byBzZWUgaGVyZQo=
total_countintegerrequiredThe total number of aliases in the index matching the request filters. May change between pages under concurrent modifications.
Example: 3