Retrieve usage

GET

https://{your_space_name}.signalwire.com/api/space/usage

GET

/api/space/usage

curl https://{your_space_name}.signalwire.com/api/space/usage \
     -u "<project_id>:<api_token>"

{
  "type": "usage",
  "month": "2026-08",
  "total_in_microdollars": 300,
  "total_in_dollars": 0.0003,
  "usage_by_kind": [
    {
      "kind": "pstn_outbound",
      "description": "Outbound Voice Minutes",
      "amount_in_microdollars": 4820000,
      "amount_in_dollars": 4.82
    }
  ],
  "projects": [
    {
      "id": "4d5e6f70-8192-4a3b-8c4d-5e6f70819234",
      "name": "Root Project",
      "amount_in_microdollars": 4820000,
      "amount_in_dollars": 4.82,
      "usage_by_kind": [
        {
          "kind": "pstn_outbound",
          "description": "Outbound Voice Minutes",
          "amount_in_microdollars": 4820000,
          "amount_in_dollars": 4.82
        }
      ]
    }
  ]
}

Returns company-wide usage for a month: the total, usage by kind, and usage per project. month defaults to the current month, so calling with no parameters returns usage so far this month.

Usage is computed on request from the usage reporting pipeline, so the response is 502 when that pipeline is unavailable.

Permissions

Authenticate with a Personal access token whose holder is an owner or admin of the space. A project API token is not accepted on this endpoint, and a Personal access token has no scopes: the holder’s role in the space is the whole authorization decision.

Returns company-wide usage for a month: the total, usage by kind, and usage per project. `month` defaults to the current month, so calling with no parameters returns usage so far this month. Usage is computed on request from the usage reporting pipeline, so the response is `502` when that pipeline is unavailable. #### Permissions Authenticate with a [Personal access token](/docs/apis/authorization#personal-access-tokens) whose holder is an owner or admin of the space. A project API token is not accepted on this endpoint, and a Personal access token has no scopes: the holder's role in the space is the whole authorization decision.

Authentication

AuthorizationBasic

Personal access token authentication for space-wide administration.

Send HTTP Basic auth with an empty username and the Personal access token as the password. A Personal access token carries your own authority rather than a project’s: it is created from your user menu in the Dashboard, is prefixed pat_, and has no scopes. The holder must be an owner or admin of the space named by the subdomain, and the token acts only on that space.

Example:

Authorization: Basic base64(:pat_...)

Personal access token authentication for space-wide administration. Send HTTP Basic auth with an empty username and the Personal access token as the password. A Personal access token carries your own authority rather than a project's: it is created from your user menu in the Dashboard, is prefixed `pat_`, and has no scopes. The holder must be an owner or admin of the space named by the subdomain, and the token acts only on that space. Example: ``` Authorization: Basic base64(:pat_...) ```

Query parameters

monthstringOptionalformat: "^\d{4}-\d{2}$"

The calendar month, as YYYY-MM. Defaults to the current month. A month before the space existed is rejected with month_precedes_space_creation, and a future month with month_is_in_the_future.

Response

The request has succeeded.

typeenum

The object type. Always usage.

monthstring

The calendar month the usage covers, as YYYY-MM.

total_in_microdollarslong

The total usage in microdollars.

total_in_dollarsdouble

The total usage in US dollars.

usage_by_kindlist of objects

Company-wide usage broken down by kind.

projectslist of objects

Usage per project, each with its own breakdown by kind.

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

500

Internal Server Error

502

Bad Gateway Error