Organization usage API
The organization usage API returns the billable active-user count shown on a Buildkite organization's Usage > Platform page. Use this endpoint to monitor active-user counts programmatically, for example, to track usage against a contracted user allowance.
Any organization member can use this endpoint. The API access token must include the read_organizations scope and grant access to the requested organization.
Get organization usage
curl -H "Authorization: Bearer $TOKEN" \
"https://api.buildkite.com/v2/organizations/{org.slug}/usage"
{
"active_users_count": 42
}
Required scope: read_organizations
Success response: 200 OK
Response fields
| Field | Type | Description | |||
|---|---|---|---|---|---|
| Field | active_users_count |
Type | integer | Description | Number of distinct billable users active during the current usage summary period. |
For a billing parent organization, the count includes activity from its linked billing child organizations. A user active in more than one linked organization is counted once.
Usage period
The usage summary period matches the period shown on the organization's Usage page:
- Monthly subscriptions: The current billing period.
- Annual subscriptions: The current calendar month and the previous six calendar months, rather than the full annual billing period.
Error responses
403 Forbidden |
The token does not have the read_organizations scope. |
|---|---|
404 Not Found |
The organization does not exist, or the authenticated user or token cannot access it. |
503 Service Unavailable |
Usage data is temporarily unavailable. Retry the request. |