# List workspaces

`GET /workspaces`

:::code-group
```bash title="cURL"
curl --request GET \
  --url https://api.pinecone.io/workspaces \
  --header 'Api-Key: <api-key>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'
```

```python title="Python"
import requests

url = "https://api.pinecone.io/workspaces"

headers = {
    "Api-Key": "<api-key>",
    "X-Pinecone-Api-Version": "<x-pinecone-api-version>"
}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript title="JavaScript"
const options = {method: "GET", headers: {"Api-Key": "<api-key>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>"}};

fetch("https://api.pinecone.io/workspaces", options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php title="PHP"
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pinecone.io/workspaces",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Api-Key: <api-key>",
    "X-Pinecone-Api-Version: <x-pinecone-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go title="Go"
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pinecone.io/workspaces"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Api-Key", "<api-key>")
	req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java title="Java"
HttpResponse<String> response = Unirest.get("https://api.pinecone.io/workspaces")
  .header("Api-Key", "<api-key>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .asString();
```

```ruby title="Ruby"
require 'uri'
require 'net/http'

url = URI("https://api.pinecone.io/workspaces")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Api-Key"] = '<api-key>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'

response = http.request(request)
puts response.read_body
```
:::

:::code-group
```json title="200"
{
  "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"
    }
  ]
}
```

```json title="401"
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}
```

```json title="500"
{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}
```
:::

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - |  |

An API Key is required to call Pinecone APIs. Get yours from the [console](https://app.pinecone.io/).

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-07` | Required date-based version header |

#### Query Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `limit?` | `integer` | `10` | The number of results to return per page. Required range: 1 <= x <= 100 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `paginationToken?` | `string` | - | The token to use to retrieve the next page of results. |

#### Response

`200` — This operation returns a list of all the workspaces that you have previously created, and which are associated with the given project.

The list of workspaces that exist in the project.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `workspaces` | `object[]` | - | List of workspaces in the project |

:::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | - | 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 '-'. Required string length: 1 - 45. Example: example-workspace |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `object` | - | 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. |

::::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `byoc` | `object` | - | Configuration needed to create a workspace in a BYOC (Bring Your Own Cloud) environment. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `environment` | `string` | - | The BYOC environment where the workspace's contexts are hosted. Example: aws-us-east-1-b921.byoc |
:::
::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `host` | `string` | - | The URL address where the workspace is hosted. Example: production-c01b5b5.wksp.prod.pinecone.io |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `created_at` | `string` | - | The date and time the workspace was created. Example: 2026-06-21T00:00:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `updated_at` | `string` | - | The date and time the workspace was last updated. Example: 2026-06-21T00:00:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `object` | - | The current status of the workspace. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ready` | `boolean` | - | Whether the workspace is ready for use. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `string` | - | The state of the workspace. Possible values: Initializing, InitializationFailed, Ready, or Terminating. |
:::
:::::

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pagination?` | `object` | - | Pagination information. Present only when more results are available; absent on the final page. |

:::accordion{title="Show child attributes"}
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `next` | `string` | - | The token to use to retrieve the next page of results. Example: dXNlcl9pZD11c2VyXzE= |
:::

## Related pages

- [Create a workspace](./control-plane-create-a-workspace.md)
- [Describe a workspace](./control-plane-describe-a-workspace.md)
- [Delete a workspace](./control-plane-delete-a-workspace.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.