Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

List workspace rate limits

GET
/v1/workspace/rate-limits
// Workspace limits matter with several workspaces, or one that kept a limit after a deletion.
const { data } = await bird.workspace.rateLimits.list();
for (const policy of data) {
  // Check usage.status first: workspace_remaining is also null when the
  // workspace has no limit of its own or its usage is not measured yet.
  console.log(policy.key, policy.limit, policy.usage.workspace_remaining);
}
Odpowiedź200
{
  "data": [
    {
      "key": "email_send",
      "workspace_limit": {
        "status": "active"
      },
      "limit_source": "manual",
      "attribution": {
        "status": "unavailable"
      },
      "usage": {
        "status": "available"
      }
    }
  ]
}

Only relevant to organizations with several workspaces, or one left with a workspace limit or enabled allocation after a deletion. When deleting workspaces leaves one, its manual limits apply until removed or expired, and enabled allocation continues. Without an active manual limit or allocation, one workspace uses the shared organization limit.

Returns every rate-limit policy as it applies to the current workspace: the organization limit shared by all workspaces, any manual or automatic workspace limit, and the remaining capacity observed in the current window.

A workspace limit is not reserved capacity. A request is refused when either the organization limit or the workspace limit is reached. When usage cannot be read, usage.status is unavailable and the remaining counts are null. usage.workspace_remaining is also null when neither a manual nor an automatic limit applies, or attribution.status is not ready, so check usage.status before treating null as a failed read.

Rate limits are served from the organization's home region. A request sent to another region returns 421 Misdirected Request; retry it on that region's host.

Treść odpowiedzi

data
array of object
wymagane
Pokaż atrybuty podrzędne
data.key
string
wymagane

Stable key of the rate-limit policy.

data.name
string
wymagane
data.description
string
wymagane
data.unit
string
wymagane

What the policy counts, such as request or message.

data.window_seconds
integer
wymagane

The rolling window length in seconds.

data.organization_limit
integer
wymagane

Maximum policy units per rolling window for the whole organization, shared by all its workspaces.

data.workspace_limit
nullable object
wymagane

The workspace's own saved limit. null when none is saved; limit_source and automatic_limit then show whether an automatic share applies.

Pokaż atrybuty podrzędne
data.workspace_limit.value
integer
wymagane

Maximum policy units this workspace can use per rolling window. It can exceed the organization limit.

data.workspace_limit.status
string
wymagane

Whether the workspace limit applies.

  • active: the limit is enforced 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
wymagane

When the workspace limit stops applying. null means it has no expiry.

data.workspace_limit.updated_at
string
wymagane

When the workspace limit was last set.

data.limit
integer
wymagane

The lower of the organization limit and the workspace's active limit or automatic share. Requests can still be refused below it when other workspaces use the shared organization limit.

data.limit_source
string
wymagane

Which limit bounds the workspace's own usage.

  • manual: the workspace's own active limit.
  • automatic: the workspace's share of the organization limit under its automatic allocation.
  • organization: no workspace limit applies; only the shared organization limit does.

Possible values (may grow over time): manual, automatic, organization

data.automatic_limit
nullable integer
wymagane

The workspace's share under the organization's automatic allocation, at least 1 per window. Set only when limit_source is automatic; it is never saved as a workspace limit.

data.allocation_enabled
boolean
wymagane

Whether the organization has an automatic allocation of this policy. It can be true while limit_source is manual. When true, changing or removing this workspace's limit can change other workspaces' automatic shares.

data.attribution
object
wymagane

When workspace usage has been measured for long enough to set a new workspace limit for this policy. Readiness covers timing only; a new limit also needs an organization with several workspaces, and with one workspace only an existing unexpired limit can be changed.

Pokaż atrybuty podrzędne
data.usage
object
wymagane

Remaining capacity in the current rolling window. Taking the observation consumes no capacity, but the request that reads it counts against its own policy, api_list, like any other read. It is measured against the limits that requests were checked against when it was read, which can briefly differ from the configured top-level organization_limit and workspace_limit after a limit changes.

Pokaż atrybuty podrzędne

Powiązane zasoby

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Uzyskaj brief wdrożeniowy