---
title: "List workspace quotas"
method: GET
path: "/v1/workspace/quotas"
tags: ["quotas"]
---

# List workspace quotas

`GET /v1/workspace/quotas`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/workspace/quotas`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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`.

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The workspace's quotas.

- WorkspaceQuotaList
  - `data` WorkspaceQuota[], required
    - `key` string, required: Stable key of the quota.
    - `name` string, required
    - `description` string, required
    - `unit` string, required: What the limit counts, such as `mailboxes`, `bytes` or `days`.
    - `kind` 'counted' | 'value', 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.
    - `enforcement` 'create' | 'outbound_send' | 'value', 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.
    - `maximum_value` integer, required: The largest workspace limit this quota accepts, in its unit.
    - `organization_limit` integer, required: The organization's limit, shared by all its workspaces.
    - `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.
    - `workspace_limit` WorkspaceQuotaCeiling, required: A workspace's own limit for a quota. It is a ceiling, not reserved capacity; the organization limit still applies.
      - `value` integer, required: The workspace limit, in the quota's unit. It can exceed the organization limit. Zero allows nothing more.
      - `status` 'active' | 'expired', 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.
      - `expires_at` string, date-time, nullable, required: When the workspace limit stops applying. `null` means it has no expiry.
      - `updated_at` string, date-time, required: When the workspace limit was last set.
    - `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.
    - `usage` WorkspaceQuotaUsage, required: Current usage, measured against the organization limit that requests were checked against when it was read. That limit can briefly differ from the configured `organization_limit` after it changes.
      - `status` 'available' | 'unavailable', 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.
      - `observed_at` string, date-time, required: When usage was read.
      - `organization_limit` integer, required: The organization limit requests were checked against when usage was read.
      - `organization_used` integer, nullable, required: The organization's total usage across all its workspaces. `null` on the current-workspace endpoint or when usage is unavailable.
      - `workspace_used` integer, nullable, required: This workspace's usage. `null` when usage is unavailable.
      - `organization_remaining` integer, nullable, 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.
      - `workspace_remaining` integer, nullable, required: How much more this workspace can add under its own limit. `null` when no workspace limit applies or usage is unavailable.
      - `remaining` integer, nullable, 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` 'available' | 'unavailable', 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.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-21** `4c9ae3960f3a`: 1 info
  - endpoint added
- **2026-10-21** `c344ff42d791`: 1 breaking
  - api path removed without deprecation
- **2026-10-20** `7fc2ff366468`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/messagebird/apis/bird-api/changes/v1/workspace/quotas/get.md)

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) - [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) - [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/2360f543281a?raw)