> ## 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 usage and estimated costs by project

> Query project logs to compare recorded token usage and estimated model costs across providers, including requests made with your own API keys.

> [!NOTE]
>
> **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**](https://www.braintrust.dev/app/~/configuration/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](https://docs.braintrust.dev/reference/sql/functions.md#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](https://docs.braintrust.dev/integrations/ai-providers/custom.md#model-metadata).

## Find usage for a project

### Query project logs

1. Go to [** Query**](https://www.braintrust.dev/app/~/sql).
2. Replace `<PROJECT_ID>` in the following query with your project ID.
3. Run the query to sum recorded token usage and estimated cost by model:

```sql theme={null}
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](https://docs.braintrust.dev/reference/sql/query-structure.md) for querying other data sources.

Use the results to compare recorded usage across models. For a reusable visualization, see [Build charts](https://docs.braintrust.dev/observe/dashboards/build-charts.md).

## 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](https://docs.braintrust.dev/instrument.md).
* 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](https://docs.braintrust.dev/kb/estimated-cost-missing-in-logs-table-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](https://docs.braintrust.dev/admin/billing/optimize-costs.md#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](https://docs.braintrust.dev/reference/sql/examples.md) for additional usage-reporting patterns.
* Create reusable usage visualizations with [Build charts](https://docs.braintrust.dev/observe/dashboards/build-charts.md).


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