> ## 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.
# List namespaces
> List all namespaces in a serverless index.
Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response includes `pagination.next`, a token you pass as `paginationToken` to get the next batch of namespaces. When the response has no `pagination`, there are no more namespaces to return.
For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).
**Note:** This operation is not supported for pod-based indexes.
```bash curl theme={null}
# 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/namespaces" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-07"
```
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml get /namespaces
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:
/namespaces:
get:
tags:
- Namespace Operations
summary: List namespaces
description: >-
List all namespaces in a serverless index.
Up to 100 namespaces are returned at a time by default, in sorted order
(bitwise “C” collation). If the `limit` parameter is set, up to that
number of namespaces are returned instead. Whenever there are additional
namespaces to return, the response includes `pagination.next`, a token
you pass as `paginationToken` to get the next batch of namespaces. When
the response has no `pagination`, there are no more namespaces to
return.
For guidance and examples, see [Manage
namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces).
**Note:** This operation is not supported for pod-based indexes.
operationId: listNamespacesOperation
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: query
name: limit
description: Max number of namespaces to return per page. Defaults to 100.
schema:
default: 100
type: integer
format: int32
minimum: 1
maximum: 100
example: 10
style: form
- in: query
name: paginationToken
description: Pagination token to continue a previous listing operation.
schema:
type: string
style: form
- in: query
name: prefix
description: >-
Prefix of the namespaces to list. Acts as a filter to return only
namespaces that start with this prefix.
Must be ASCII and must not contain the NUL character, matching the
namespace names it filters. An empty prefix matches every namespace.
schema:
type: string
pattern: ^[\x01-\x7F]*$
maxLength: 512
example: prefixExample
style: form
responses:
'200':
description: A successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListNamespacesResponse'
'400':
description: Bad request. The request 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:
ListNamespacesResponse:
type: object
properties:
namespaces:
description: The list of namespaces belonging to this index.
type: array
items:
$ref: '#/components/schemas/NamespaceDescription'
pagination:
$ref: '#/components/schemas/Pagination'
total_count:
example: 25
description: The total number of namespaces in the index matching the prefix
type: integer
format: int32
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
NamespaceDescription:
description: A description of a namespace, including the name and record count.
type: object
properties:
name:
example: example-namespace
description: The name of the namespace.
type: string
record_count:
example: '20000'
description: >-
The total number of records in the namespace. A 64-bit integer,
serialized as a decimal string.
type: string
format: uint64
schema:
example:
fields:
description:
filterable: true
genre:
filterable: true
year:
filterable: true
description: >-
Schema for the behavior of Pinecone's internal metadata index. By
default, all metadata is indexed; when `schema` is present, only
fields which are present in the `fields` object with a `filterable:
true` are indexed. Note that `filterable: false` is not currently
supported.
x-component-name: MetadataSchema
type: object
properties:
fields:
description: >-
A map of metadata field names to their configuration. The field
name must be a valid metadata field name. The field name must be
unique. At most 50 fields may be declared.
Field names may not begin with `$`, which introduces a filter
operator. When declared at index creation, names beginning with
`_` are also rejected (reserved for internal use).
type: object
additionalProperties:
type: object
properties:
filterable:
description: >-
Whether the field is indexed and can be used in filters.
Must be present and must be `true`: omitting it, or
sending `false` or `null`, is rejected with `Field
'' is set to filterable: false. Only filterable:
true is supported.` To leave a field unindexed, omit it
from `fields` entirely.
type: boolean
enum:
- true
required:
- filterable
maxProperties: 50
indexed_fields:
description: A list of all indexed metatadata fields in the namespace
type: object
properties:
fields:
example:
- genre
- year
- author
type: array
items:
type: string
size_bytes:
example: '1048576'
description: >-
The total size of the namespace's data, in bytes, as a 64-bit
integer serialized as a decimal string. Approximate: data written
before size tracking reads as 0, and recently deleted data may still
be counted; compaction converges the value.
type: string
format: uint64
Pagination:
type: object
properties:
next:
example: Tm90aGluZyB0byBzZWUgaGVyZQo=
type: string
required:
- next
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/).
````