Export billing usage data for reporting

Applies to:

Plan - Enterprise
Deployment - Any
Data plane - v2.1 or later
Retrieve Braintrust billing usage via an API workaround for internal reporting or loading into a data warehouse.

Summary

Retrieve Braintrust usage data for internal reporting, dashboards, or loading into a data warehouse using POST https://www.braintrust.dev/api/actions/getOrganizationUsage.

This endpoint is a temporary workaround. It may change or stop working, and continued support is not guaranteed.

What is happening

The endpoint returns aggregated usage for a selected date range, grouped by organization or project, with daily or monthly granularity. Results can include logs usage, score counts, token usage, and associated cost fields. You can retrieve the data manually or schedule requests in your own pipeline to load it into your reporting system. Returned cost fields should not be assumed to match final invoice totals, which may reflect contractual commitments, credits, and other adjustments.

Fix or suggestion

API pull with `getOrganizationUsage` (ad-hoc or scripted)

Prerequisites:

An API key or service token that has the organization update permission.

Example cURL:

curl --request POST \
  --url 'https://www.braintrust.dev/api/actions/getOrganizationUsage' \
  --header "Authorization: Bearer ${BRAINTRUST_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "function_args": {
      "orgId": "<organization-id>",
      "startDate": "<YYYY-MM-DD>",
      "endDate": "<YYYY-MM-DD>",
      "timezone": "UTC",
      "granularity": "day",
      "groupBy": "project",
      "metrics": ["logs", "scores", "topics", "inference"],
      "projectIds": ["<project-id-1>", "<project-id-2>"]
    }
  }'

Built-in model usage is returned in the inference array, with entries containing model, tokenType, tokens, and an optional cost. The top-level inputTokens and outputTokens fields represent Topics usage. Illustrative response example for one project and one day. Values are examples, not billing rates. Optional cost fields are omitted from this Enterprise example:

{
  "groupBy": "project",
  "data": [
    {
      "date": "<YYYY-MM-DD>",
      "startDate": "<YYYY-MM-DD>",
      "endDate": "<YYYY-MM-DD>",
      "projectId": "<project-uuid>",
      "projectName": "<project-name>",
      "logsUsage": 0.5,
      "scoresUsage": 10,
      "inputTokens": 1.8,
      "outputTokens": 0.2,
      "inference": [
        {
          "model": "<model-id>",
          "tokenType": "input",
          "tokens": 1000
        },
        {
          "model": "<model-id>",
          "tokenType": "output",
          "tokens": 200
        }
      ]
    }
  ]
}

Usage values are numbers. Cost fields are strings and may be omitted when unavailable. Fields also depend on the requested metrics and available usage.

Enterprise pricing and cost fields

This endpoint is useful for retrieving usage quantities, but it does not reliably report your Enterprise contract charges. Cost fields such as logsCost, scoresCost, inputTokensCost, and outputTokensCost may be zero or unavailable even when usage is non-zero. Enterprise pricing is customized to your agreement. Reconcile the exported usage against your contractual rates and billing terms, including any commitments, credits, and overage pricing. This endpoint does not perform that reconciliation for you. Do not calculate your invoice total by summing its cost fields. If you need help confirming the applicable rates or terms, contact your Braintrust account team. Permissions and best practices:

Use a dedicated service token for automated exports or API pulls. Grant only the permissions required for the task.
Rotate the service token regularly and store it in a secrets manager.
Limit the IP range or VPC access for server-side ingestion jobs where possible.

How to confirm it worked

For API pulls: call POST https://www.braintrust.dev/api/actions/getOrganizationUsage for a known date range. Compare summed consumption to the Billing UI’s Usage analytics report.

Notes

This endpoint only returns usage within the most recent rolling 100 days. Splitting requests into smaller date ranges does not allow access to older history. For longer-term reporting, export regularly and retain the results in your reporting system.
Project-level usage is available from 2026-09-01 onward. A single API call returns up to 200 projects when projectIds is omitted.
For a UI view of usage, see Monitor usage.

​Summary

​What is happening

​Fix or suggestion

​API pull with getOrganizationUsage (ad-hoc or scripted)

​Enterprise pricing and cost fields

​How to confirm it worked

​Notes

Summary

What is happening

Fix or suggestion

API pull with `getOrganizationUsage` (ad-hoc or scripted)

Enterprise pricing and cost fields

How to confirm it worked

Notes