Organization usage API

Get organization usage

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.buildkite.com/v2/organizations/{org.slug}/usage"

Success response: 200 OK. The following response excerpts omit other fields and metrics.

Concurrent agents:

{
  "reporting_period": { "from": "2026-10-01", "to": "2026-10-27" },
  "pipelines": {
    "self_hosted_concurrent_agents_p95": {
      "value": 52,
      "unit": "agents",
      "definition": "95th percentile of the daily sums of each organization's peak self-hosted agent count."
    }
  }
}

Test Engine usage:

{
  "reporting_period": { "from": "2026-10-01", "to": "2026-10-27" },
  "test_engine": {
    "test_executions": {
      "value": 120000,
      "unit": "executions",
      "definition": "Total recorded test executions."
    },
    "otel_ingested_bytes": {
      "value": 1500000000,
      "unit": "bytes",
      "definition": "Decoded OpenTelemetry trace bytes ingested, excluding test-result span bytes."
    }
  }
}

Response fields

Each product metric includes a value, a unit, and a readable definition. Usage figures do not represent charges or included limits.

The test_engine.otel_ingested_bytes metric reports metered, uncompressed OpenTelemetry trace bytes after plan-policy drops, excluding bytes carrying test results in root test spans. Other root spans remain included.

This is the same byte meter used by the Usage page and billing, before conversion to gigabytes or any included allowance. The value is not the compressed upload size, a charge, or allowance-adjusted overage. The metric is 0 when no usage is recorded.

Usage period

All metrics default to calendar month to date. For example, on October 27, the reporting period is October 1–27. All boundaries use UTC, and today's figures are partial.

Supply optional from and to query parameters together, for example, ?from=2026-09-15&to=2026-10-14. Both use YYYY-MM-DD dates and apply to all metrics, including active_users_count.

• from must be no earlier than today minus three calendar months.
• to must be on or after from and no later than today.
• The latest to is one calendar month after from, preserving month-end alignment, minus one day.

Users active in more than one included organization count once across the selected reporting period, including ranges that cross a calendar-month boundary.

To compare the response with the organization's Usage page, select the same dates on both. Cached responses and ongoing ingestion can cause temporary differences. Use a completed date range that excludes today to reduce those differences.

Error responses