> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# View model token usage and estimated costs

> Query recorded token usage and estimated model costs for one or multiple projects, including requests made with your own provider API keys.

> [!NOTE]
>
> **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](https://docs.braintrust.dev/admin/billing/monitor-usage.md#view-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](https://docs.braintrust.dev/reference/sql/functions.md#cost-functions).

## Query one project

Open the [**Query** page](https://www.braintrust.dev/app/~/sql) from the organization sidebar and run the following query, replacing `<PROJECT_ID>` with your project ID:

```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.braintrust.dev/kb/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](https://docs.braintrust.dev/kb/configure-custom-model-costs-for-estimation). If costs are missing when using project-level custom providers, see [Estimated cost missing with project-level providers](https://docs.braintrust.dev/kb/estimated-cost-missing-in-logs-table-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](https://docs.braintrust.dev/reference/sql/query-structure.md).
* 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](https://docs.braintrust.dev/reference/sql/examples.md) for additional reporting patterns.
* Build reusable usage visualizations with [Build charts](https://docs.braintrust.dev/observe/dashboards/build-charts.md).
* Configure [custom model pricing](https://docs.braintrust.dev/kb/configure-custom-model-costs-for-estimation) when registry pricing does not match your models.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.