Sign in
Space Billing

Retrieve usage

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.

get/api/space/usage

Query parameters

monthstring

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.

type'usage' required

The object type. Always usage.

monthstring required

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

total_in_microdollarsinteger required

The total usage in microdollars.

total_in_dollarsnumber double required

The total usage in US dollars.

Example response

{
  "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": [
    {
      "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
        }
      ]
    }
  ]
}

Changes

Changed in 1 of the 161 revisions of this API.1

Of the 161 revisions, 3 have a changelog that could not be searched.