View model token usage and estimated costs

Applies to:

Plan - Any
Deployment - Any
Query token usage and estimated model costs in project logs, including requests made with third-party provider API keys.

Summary

Query project logs to view recorded token usage and estimated costs by model. Use one project ID for a project-level breakdown, or multiple IDs for combined usage across projects. These queries include only requests logged to Braintrust. They do not show all activity on a provider account or replace your provider invoice.

How usage and cost reporting work

The built-in inference charts under Billing > Usage analytics cover Braintrust built-in model and Topics usage. Requests made with your own third-party provider API keys do not appear in those charts. See Monitor usage. To inspect those requests, query the LLM spans recorded in your project. Token reporting depends on the metrics your tracing integration records. Configuring an AI provider key alone does not record every request made with that key. estimated_cost() uses the span’s logged metrics.estimated_cost when present. Otherwise, it calculates an estimate from token metrics and model-registry pricing. See Cost functions.

Query one project

Open the Query page from the organization sidebar and run the following query, replacing <PROJECT_ID> with your project ID:

SELECT
  metadata.model AS model,
  SUM(metrics.prompt_tokens) AS input_tokens,
  SUM(metrics.completion_tokens) AS output_tokens,
  SUM(estimated_cost()) AS estimated_cost_usd
FROM project_logs('<PROJECT_ID>', shape => 'spans')
WHERE created >= now() - interval 7 day
  AND span_attributes.type = 'llm'
GROUP BY metadata.model
ORDER BY estimated_cost_usd DESC;

Change the date range in the WHERE clause as needed.
To filter for a model family, add a condition such as AND metadata.model ILIKE '%claude%'.
To select one model, use AND metadata.model = '<model-name>', matching the name recorded in your spans.

The query groups requests by model name. It does not separate requests by API key or provider account.

Query multiple projects

Pass multiple project IDs to project_logs() to combine their usage. This example groups the combined results by day and model:

SELECT
  date_trunc('day', created) AS day,
  metadata.model AS model,
  SUM(metrics.prompt_tokens) AS input_tokens,
  SUM(metrics.completion_tokens) AS output_tokens,
  SUM(metrics.prompt_cached_tokens) AS cached_input_tokens,
  SUM(estimated_cost()) AS estimated_cost_usd
FROM project_logs(
  '<PROJECT_ID_1>',
  '<PROJECT_ID_2>',
  '<PROJECT_ID_3>',
  shape => 'spans'
)
WHERE created >= now() - interval 7 day
  AND span_attributes.type = 'llm'
GROUP BY 1, 2
ORDER BY 1, 2;

These results combine the selected projects rather than returning separate totals for each project. Run the single-project query separately when you need an individual project breakdown. For breakdowns by user or prompt, see Query token distribution by user or prompt with SQL.

Understand estimated costs

Cost accuracy depends on the data recorded and the pricing used:

If you log metrics.estimated_cost, Braintrust uses that value.
Otherwise, Braintrust estimates cost from recorded token metrics and model-registry pricing.
To reflect negotiated rates or discounts, factor them into the cost you log as metrics.estimated_cost.
Account-level credits and other invoice adjustments may still cause your final bill to differ.

Compare results with your provider’s billing reports before treating them as actual spend. Missing cost estimates do not establish that requests were free, and an aggregate may not include costs for every matching span. For custom pricing or discounted costs, see Configure custom model costs for estimation. If costs are missing when using project-level custom providers, see Estimated cost missing with project-level providers.

Confirm the results

Confirm that the query covers the intended projects and date range.
Compare model names and token counts with representative LLM spans.
If fields are missing, check that your tracing integration records model metadata and token metrics.
Check representative cost values before relying on aggregate totals.

Notes

These queries read project logs. Experiment traces require an experiment data source. See SQL query structure.
Token metrics and model metadata should be recorded on the same LLM spans for model-level reporting.
Avoid recording duplicate token usage on multiple LLM spans, since these queries sum the recorded values.
Provider billing may include charges that token-based reporting does not capture.

Next steps

Explore example SQL queries for additional reporting patterns.
Build reusable usage visualizations with Build charts.
Configure custom model pricing when registry pricing does not match your models.

​Summary

​How usage and cost reporting work

​Query one project

​Query multiple projects

​Understand estimated costs

​Confirm the results

​Notes

​Next steps

Summary

How usage and cost reporting work

Query one project

Query multiple projects

Understand estimated costs

Confirm the results

Notes

Next steps