---
title: "List workspace quotas"
canonical: "https://bird.com/docs/api/reference/list-workspace-quotas"
---

# List workspace quotas

`GET /v1/workspace/quotas`

Returns each resource and value quota as it applies to the current workspace: the organization limit shared by
all workspaces, the workspace's own limit when one is set, and this workspace's current usage.
Organization usage and shared remaining capacity are withheld: `organization_used`,
`organization_remaining` and `remaining` are always `null` on this endpoint.

A workspace limit is a ceiling, not reserved capacity. Each quota's `enforcement` says how both limits apply:
`create` refuses a creation that would pass either one, `outbound_send` refuses outbound sends once the bytes
already held reach either one, and `value` bounds a setting when it is chosen. `usage` is `null` for a `value`
quota. When usage cannot be read, `usage.status` is `unavailable` and the counts are `null`.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.
- `https://platform.bird.com`: Region-independent endpoint for authentication and account administration.
- `http://localhost:8080`: Local development.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

- `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.

## Code samples

**TypeScript**

```ts
const { data } = await bird.workspace.quotas.list();
for (const quota of data) {
  console.log(quota.key, quota.limit, quota.organization_limit);
}
```

Examples: [TypeScript](/docs/api/reference/list-workspace-quotas.ts.md) · [Python](/docs/api/reference/list-workspace-quotas.py.md) · [Go](/docs/api/reference/list-workspace-quotas.go.md) · [PHP](/docs/api/reference/list-workspace-quotas.php.md) · [CLI](/docs/api/reference/list-workspace-quotas.cli.md) · [MCP](/docs/api/reference/list-workspace-quotas.mcp.md) · [cURL](/docs/api/reference/list-workspace-quotas.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "key": "email_mailboxes_max",
      "unit": "mailboxes",
      "kind": "counted",
      "enforcement": "create",
      "organization_source": "default",
      "workspace_limit": {
        "status": "active"
      },
      "usage": {
        "status": "available"
      }
    }
  ],
  "configuration": "available"
}
```

## Header parameters

- `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
- `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

## Response body

- `data` (array of object, required)
- `data.key` (string, required): Stable key of the quota.
- `data.name` (string, required)
- `data.description` (string, required)
- `data.unit` (string, required): What the limit counts, such as `mailboxes`, `bytes` or `days`.
- `data.kind` (string, required)

  What the quota limits.

  - `counted`: an amount the workspace accumulates, such as mailboxes or stored bytes. Usage is reported.
  - `value`: the largest setting a resource may be given, such as a retention period. No usage is counted.

  Possible values: `counted`, `value`
- `data.enforcement` (string, required)

  When the limits are applied.

  - `create`: a request that would add more than the limits allow is refused, and nothing is created.
  - `outbound_send`: sending is refused once the bytes already stored reach a limit. The size of the message being sent is not counted in advance, and incoming mail is still accepted.
  - `value`: a setting above the limit is refused when it is chosen. Existing resources keep their settings.

  Possible values: `create`, `outbound_send`, `value`
- `data.maximum_value` (integer, required): The largest workspace limit this quota accepts, in its unit.
- `data.organization_limit` (integer, required): The organization's limit, shared by all its workspaces.
- `data.organization_source` (string, required)

  Where the organization limit comes from.

  - `default`: Bird's standard limit.
  - `plan`: the organization's plan.
  - `override`: a limit Bird set for the organization.

  Possible values (may grow over time): `default`, `plan`, `override`
- `data.workspace_limit` (nullable object, required): The workspace's own limit. `null` when the workspace has none and uses only the shared organization limit.
- `data.workspace_limit.value` (integer, required): The workspace limit, in the quota's unit. It can exceed the organization limit. Zero allows nothing more.
- `data.workspace_limit.status` (string, required)

  Whether the workspace limit applies.

  - `active`: the limit applies alongside the organization limit.
  - `expired`: the limit passed its expiry and no longer applies. It stays visible until it is replaced or removed.

  Possible values: `active`, `expired`
- `data.workspace_limit.expires_at` (nullable string, required): When the workspace limit stops applying. `null` means it has no expiry.
- `data.workspace_limit.updated_at` (string, required): When the workspace limit was last set.
- `data.limit` (integer, required): The lower of the organization limit currently applied to requests and any active workspace limit. The applied organization limit can briefly differ from the configured `organization_limit` after a change. A request can still be refused below this value when other workspaces use the shared organization limit.
- `data.usage` (nullable object, required): Current usage. `null` for a `value` quota, which counts nothing.
- `data.usage.status` (string, required)

  Whether current usage could be read.

  - `available`: the counts reflect usage at `observed_at`.
  - `unavailable`: usage could not be read. The counts are unknown, not zero.

  Possible values: `available`, `unavailable`
- `data.usage.observed_at` (string, required): When usage was read.
- `data.usage.organization_limit` (integer, required): The organization limit requests were checked against when usage was read.
- `data.usage.organization_used` (nullable integer, required): The organization's total usage across all its workspaces. `null` on the current-workspace endpoint or when usage is unavailable.
- `data.usage.workspace_used` (nullable integer, required): This workspace's usage. `null` when usage is unavailable.
- `data.usage.organization_remaining` (nullable integer, required): How much more the whole organization can add, shared by all its workspaces. `null` on the current-workspace endpoint or when usage is unavailable.
- `data.usage.workspace_remaining` (nullable integer, required): How much more this workspace can add under its own limit. `null` when no workspace limit applies or usage is unavailable.
- `data.usage.remaining` (nullable integer, required): How much more this workspace can add now, the lower of `organization_remaining` and any `workspace_remaining`. `null` on the current-workspace endpoint or when usage is unavailable.
- `configuration` (string, required)

  Whether workspace limits can be set.

  - `available`: workspace limits can be set and changed.
  - `unavailable`: new workspace limits cannot be set in this region yet. Existing workspace limits still apply and can be removed.

  Possible values: `available`, `unavailable`

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)