> ## 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 workspaces > List the workspaces in the project. Results are paginated; the `pagination` object is omitted when there are no further results. ## OpenAPI ````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/nexus_control_2026-07.oas.yaml get /workspaces openapi: 3.0.3 info: title: Pinecone Nexus Control Plane API description: Control-plane API for Pinecone Nexus. 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://api.pinecone.io description: Production API endpoints security: - ApiKeyAuth: [] tags: - name: Manage Workspaces description: Actions that manage Nexus workspaces externalDocs: description: More Pinecone.io API docs url: https://docs.pinecone.io/introduction paths: /workspaces: get: tags: - Manage Workspaces summary: List workspaces description: >- List the workspaces in the project. Results are paginated; the `pagination` object is omitted when there are no further results. operationId: list_workspaces 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: The number of results to return per page. schema: default: 10 type: integer minimum: 1 maximum: 100 style: form - in: query name: paginationToken description: The token to use to retrieve the next page of results. schema: type: string style: form responses: '200': description: >- This operation returns a list of all the workspaces that you have previously created, and which are associated with the given project. content: application/json: schema: $ref: '#/components/schemas/WorkspaceList' examples: multiple-workspaces: summary: A list containing two workspaces. value: pagination: next: dXNlcl9pZD11c2VyXzE= workspaces: - created_at: '2026-06-01T00:00:00.000Z' host: >- production-c01b5b5.wksp.aws-us-east-1-b921.byoc.pinecone.io name: production spec: byoc: environment: aws-us-east-1-b921.byoc status: ready: true state: Ready updated_at: '2026-06-11T13:00:00.000Z' - created_at: '2026-06-10T00:00:00.000Z' host: >- staging-7a1f9c1.wksp.aws-us-east-1-b921.byoc.pinecone.io name: staging spec: byoc: environment: aws-us-east-1-b921.byoc status: ready: true state: Ready updated_at: '2026-06-11T13:00:00.000Z' no-workspaces: summary: No workspaces created yet. value: workspaces: [] '401': description: 'Unauthorized. Possible causes: Invalid API key.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Unauthorized value: error: code: UNAUTHENTICATED message: Invalid API key. status: 401 '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-server-error: summary: Internal server error value: error: code: UNKNOWN message: Internal server error status: 500 components: schemas: WorkspaceList: description: The list of workspaces that exist in the project. type: object properties: workspaces: description: List of workspaces in the project type: array items: $ref: '#/components/schemas/WorkspaceModel' pagination: $ref: '#/components/schemas/PaginationResponse' required: - workspaces ErrorResponse: example: error: code: QUOTA_EXCEEDED message: >- The request exceeds your project quota. Upgrade your account or adjust your project settings to increase the quota. status: 429 description: The response shape used for all error responses. type: object properties: status: example: 500 description: The HTTP status code of the error. type: integer error: example: code: INVALID_ARGUMENT message: The request contained an invalid argument. description: Detailed information about the error that occurred. type: object properties: code: description: >- The code of the error. Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`, `DEADLINE_EXCEEDED`, `QUOTA_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`, `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `UNIMPLEMENTED`, `INTERNAL`, `UNAVAILABLE`, `DATA_LOSS`, `FORBIDDEN`, `UNPROCESSABLE_ENTITY`, or `PAYMENT_REQUIRED`. x-enum: - OK - UNKNOWN - INVALID_ARGUMENT - DEADLINE_EXCEEDED - QUOTA_EXCEEDED - NOT_FOUND - ALREADY_EXISTS - PERMISSION_DENIED - UNAUTHENTICATED - RESOURCE_EXHAUSTED - FAILED_PRECONDITION - ABORTED - OUT_OF_RANGE - UNIMPLEMENTED - INTERNAL - UNAVAILABLE - DATA_LOSS - FORBIDDEN - UNPROCESSABLE_ENTITY - PAYMENT_REQUIRED type: string message: example: The request contained an invalid argument. description: A human-readable description of the error type: string details: description: >- Additional information about the error. This field is not guaranteed to be present. type: object required: - code - message required: - status - error WorkspaceModel: description: Describes a workspace, a project-scoped grouping of contexts. type: object properties: name: example: example-workspace description: > The name of the workspace. Resource name must be 1-45 characters long, start and end with an alphanumeric character, and consist only of lower case alphanumeric characters or '-'. type: string minLength: 1 maxLength: 45 spec: $ref: '#/components/schemas/WorkspaceSpec' host: example: production-c01b5b5.wksp.prod.pinecone.io description: The URL address where the workspace is hosted. type: string created_at: example: '2026-06-21T00:00:00.000Z' description: The date and time the workspace was created. type: string format: date-time updated_at: example: '2026-06-21T00:00:00.000Z' description: The date and time the workspace was last updated. type: string format: date-time status: example: ready: true state: Ready description: The current status of the workspace. type: object properties: ready: description: Whether the workspace is ready for use. type: boolean state: description: >- The state of the workspace. Possible values: `Initializing`, `InitializationFailed`, `Ready`, or `Terminating`. x-enum: - Initializing - InitializationFailed - Ready - Terminating type: string required: - ready - state required: - name - spec - host - status - created_at - updated_at PaginationResponse: example: next: dXNlcl9pZD11c2VyXzE= description: >- Pagination information. Present only when more results are available; absent on the final page. type: object properties: next: example: dXNlcl9pZD11c2VyXzE= description: The token to use to retrieve the next page of results. type: string required: - next WorkspaceSpec: description: > The spec object defines the environment in which the workspace's contexts are created. Workspaces are created in a customer-managed BYOC (Bring Your Own Cloud) environment. type: object properties: byoc: $ref: '#/components/schemas/WorkspaceByocSpec' required: - byoc additionalProperties: false WorkspaceByocSpec: example: environment: aws-us-east-1-b921.byoc title: BYOC description: >- Configuration needed to create a workspace in a BYOC (Bring Your Own Cloud) environment. type: object properties: environment: example: aws-us-east-1-b921.byoc description: The BYOC environment where the workspace's contexts are hosted. type: string required: - environment 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/). ````