View model usage and estimated costs by project

Applies to:

Plan - Any
Deployment - Any
Retrieve recorded token counts and estimated model costs for a project, including requests made with third-party provider API keys.

Summary

Use project logs to view token counts and estimated model costs for requests recorded in Braintrust, including requests made with your own provider API keys. Query usage by model within a project, then filter the results for the models you want to inspect. These results cover the requests logged to Braintrust. They are not a complete account of your provider usage or a replacement for your provider invoice.

What is happening

The built-in inference charts in Settings > Billing under Usage analytics cover Braintrust built-in model and Topics usage. To report on third-party model usage, query the traces recorded in your project. The requests must be logged to Braintrust with model metadata and token metrics. Configuring a provider key alone does not record every request made with that key. The estimated_cost() function uses the logged metrics.estimated_cost value when available. Otherwise, it calculates cost using token metrics and model-registry pricing. Cost coverage therefore depends on the data recorded and the pricing available for the model. See Cost functions. To reflect negotiated rates or discounts, log the cost in USD as metrics.estimated_cost on the LLM span. For custom models, cost estimation uses pricing from organization providers, not project providers. See Model metadata.

Find usage for a project

Query project logs

Go to Query.
Replace <PROJECT_ID> in the following query with your project ID.
Run the query to sum recorded token usage and estimated cost by model:

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 NULLS LAST;

Change the date range in the WHERE clause as needed.
To restrict the results to a model family, add a filter such as AND metadata.model ILIKE '%claude%'.
To match one model exactly, use AND metadata.model = '<model-name>', replacing the placeholder with the name recorded in your logs.
Model-name filters select matching names, not a specific provider account or API key.
Experiment traces are stored separately and are not included in this project_logs query. See SQL query structure for querying other data sources.

Use the results to compare recorded usage across models. For a reusable visualization, see Build charts.

Confirm it worked

Confirm that the query covers the intended project and date range.
Check that model names and token counts match representative LLM spans in the project’s logs.
If model names or token metrics are missing, inspect your tracing setup. See Instrument your application.
If costs are missing or unexpected, check the span’s logged cost, token metrics, and model name before relying on the total. A missing estimate does not establish that the request was free.
If you use custom project-level providers and costs are missing, see Estimated cost missing with project-level providers.

Notes

Usage recorded under the same model name is combined into one row, even if requests used different credentials or provider accounts.
If the same call’s token metrics and cost are recorded on multiple matching LLM spans, the query includes each span in the totals. See Reduce duplicate logging.
Estimated costs may differ from provider charges because of pricing agreements, discounts, billing adjustments, or incomplete recorded data.
Token totals alone do not capture every possible charge for every model or modality. Compare with provider reporting when you need complete billing information.

Next steps

Explore example SQL queries for additional usage-reporting patterns.
Create reusable usage visualizations with Build charts.