> ## 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.

# Configure custom model costs for estimation

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Any
> *
> *

## Summary

If you don't log `metrics.estimated_cost` directly on a span, Braintrust falls back to the model registry to estimate cost from token metrics and registered pricing. Custom LLM models need to be registered in Braintrust's model registry with pricing information for this fallback to produce a cost. Spans that log `metrics.estimated_cost` explicitly use that value as-is in the trace viewer and in the `estimated_cost()` SQL function.

## Configuration Steps

### Step 1: Register your custom model

Register custom model pricing on an organization-level provider. The pricing lookup used by `estimated_cost()` [does not include project-level providers](https://docs.braintrust.dev/kb/estimated-cost-missing-in-logs-table-with-project-level-providers).

Go to ** Settings** > [** Models**](https://www.braintrust.dev/app/~/configuration/models/organization). Click  **Organization provider**, then choose **Custom providers** >  **New**. On **Setup**, configure the provider, then under **Models**, click  **Custom model** and enter the model identifier recorded in your traces. See [Custom providers](https://docs.braintrust.dev/integrations/ai-providers/custom.md#setup).

### Step 2: Set pricing information

Click the  settings icon beside the custom model to open **Model options**, then configure:

* Input cost per million tokens
* Output cost per million tokens
* Cache read/write costs (if using prompt caching)

Click **Create**, or **Update** if you are editing an existing provider, to save the configuration.

### Step 3: Update span metadata

Ensure your logged spans include `metadata.model` matching the exact registered model name.

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
braintrust.log(
    metadata={"model": "your-custom-model-name"},
    # other span data
)

```

### Step 4: Query costs across projects

Use SQL to aggregate costs across multiple projects:

```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
SELECT
    metadata.model,
    day(created) AS date,
    avg(estimated_cost()) AS avg_cost,
    sum(estimated_cost()) AS total_cost
FROM project_logs('project-id-1', 'project-id-2')
WHERE created > now() - interval 7 day
  AND span_attributes.type = 'llm'
GROUP BY metadata.model, date
```

Save this query as a custom view for reuse across your organization.

For more granular breakdowns — for example, separating cached prompt cost from uncached prompt cost — use `estimated_cost_component(name)` to extract a single cost component, or `estimated_cost_breakdown()` to return all components as a JSON object. See [SQL functions](https://docs.braintrust.dev/reference/sql/functions.md#sql-functions) for the available component names.

## Log a discounted cost

If your provider applies a discount or batch pricing that Braintrust's model prices do not reflect, calculate the discounted cost (using the provider's applicable rates, including cached-token pricing where relevant) and log it in USD as `metrics.estimated_cost` on the corresponding LLM span. Supply the final cost, not the discount percentage. This overrides automatic estimation without requiring a custom model.

For example, a request costing \$0.003548 at standard rates costs \$0.001774 with a 50% discount. Log `0.001774` as `metrics.estimated_cost`. Use the provider's applicable rates, including cached-token pricing where relevant.

For existing spans, see [Update spans](https://docs.braintrust.dev/instrument/advanced-tracing.md#update-spans). You need the LLM span's `id` and must ensure the original span is flushed before updating it.


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