Skip to main content

Track and analyze AI spend with Unity Gateway

Analyze Unity Gateway spend by model, user, tag, and team with the usage dashboard, Genie, or SQL. Spend covers Databricks-hosted models and estimated spend for external models. To limit what users can spend, see Set budgets and spend limits for Unity Gateway.

For request-level analytics such as token counts and latency, see Track model usage.

Requirements​

Usage and spend system tables​

system.ai_gateway.usage records requests routed through Unity Gateway, with requester and service details, tokens, latency, and tags. Task-specific AI Function requests count toward Unity Gateway budgets but aren't recorded in this table. To view their billed usage, see View costs for AI Function workloads. See Usage table schema.

Spend is recorded in two more system tables:

View spend in the usage dashboard​

The built-in Unity Gateway usage dashboard helps you identify spending trends, compare models and users, and attribute spend to teams and projects. It includes Databricks-hosted model spend and estimated external model spend.

Open Unity Gateway > Govern > Usage Dashboard.

ai-gateway Spend tab

  • Overview: Compare model and user spend, track changes, and evaluate average spend per million tokens or per request.
  • Spend: Explore spend by model and user alongside token usage and caching. Use the User filter to focus the analysis. To rank spend by user, model, or tag, ask Genie.
  • Service tags: Apply tags to services to attribute spend to teams or projects. Select a Service Tag Key and one or more Service Tag Value entries in the global filters to focus the analysis.
  • Request tags: Send tags through request headers to attribute spend to individual workloads.
  • Coding agent sessions: Investigate high-spend sessions in the Coding Agents tab, with estimated session spend alongside token usage, models, and subagent activity.

See Built-in usage dashboard to set up and update the usage dashboard.

Attribute spend to teams and projects​

Unity Gateway attributes spend to the requesting user automatically. To attribute spend to a team or project, tag your traffic:

  • Service tags: Use when each team or project has its own model service. Every request routed through the service inherits the tag, so you set it one time.
  • Request tags: Use when several teams or projects share a model service. The caller sets the tag on each request.

To add a service tag, open the model service in Unity Gateway. On the Overview tab, select Tags > Add tags, then enter a key and value, such as team and ml-platform. Service tags appear in endpoint_tags in system.ai_gateway.usage and in custom_tags in system.billing.usage.

To add a request tag, send the Databricks-Ai-Gateway-Request-Tags header with a JSON object of string keys and values:

Text
Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}

For SDK and REST API examples, see Request tagging.

For Databricks-hosted models, use service tags, because only service tags reach system.billing.usage. For external models, both service and request tags appear in system.ai_gateway.external_model_spend. Budgets match service tags only.

Ask questions about spend with Genie​

To answer a question the dashboard doesn't show directly, ask Genie. Genie answers from the dashboard's data, so you don't need to name tables or write SQL.

  1. Open Unity Gateway > Govern > Usage Dashboard.
  2. Click Ask Genie.
  3. Ask your question in plain language. For example:
    • Which users spent the most in the last 30 days?
    • What did the ml-platform team spend last month?
    • Which models had the highest spend this week?

See Genie Agents with dashboards.

Query spend with SQL​

Use SQL for repeatable reports and precise joins.

Create a combined spend view​

The view combines Databricks-hosted model spend, recorded as DBUs in system.billing.usage and converted to list-price USD with system.billing.list_prices, with estimated external model spend, recorded in USD in system.ai_gateway.external_model_spend. Select from the view to cover all models. Create it in a schema you control:

SQL
CREATE OR REPLACE VIEW <catalog>.<schema>.ai_gateway_spend AS
WITH all_spend AS (
SELECT
'databricks_hosted' AS model_source,
u.workspace_id AS workspace_id,
u.usage_date AS usage_date,
u.usage_metadata.ai_gateway.endpoint_name AS model_service_name,
u.usage_metadata.ai_gateway.destination_model AS destination_model,
u.identity_metadata.run_by AS requester,
u.custom_tags AS service_tags,
CAST(NULL AS MAP<STRING, STRING>) AS request_tags,
u.usage_quantity AS dbus,
u.usage_quantity * lp.pricing.effective_list.default AS usd
FROM system.billing.usage u
JOIN system.billing.list_prices lp
ON u.sku_name = lp.sku_name
AND u.cloud = lp.cloud
AND u.usage_unit = lp.usage_unit
AND u.usage_end_time >= lp.price_start_time
AND (lp.price_end_time IS NULL OR u.usage_end_time < lp.price_end_time)
WHERE u.billing_origin_product = 'MODEL_SERVING'
AND u.usage_metadata.ai_gateway.endpoint_name IS NOT NULL
AND u.usage_unit = 'DBU'
AND lp.currency_code = 'USD'
UNION ALL
SELECT
'external' AS model_source,
workspace_id,
usage_date,
usage_metadata.endpoint_name,
usage_metadata.model,
identity_metadata.run_by,
custom_tags.endpoint_tags,
custom_tags.request_tags,
NULL,
usage_quantity
FROM system.ai_gateway.external_model_spend
)
SELECT * FROM all_spend;

In both branches, model_service_name is the Unity Catalog fully qualified name of the service that received the request: the model service for Databricks-hosted rows, and the model provider service that routed the request for external rows. workspace_id is the ID of the workspace associated with the usage in both sources. Requests and tokens for all models are in system.ai_gateway.usage, except task-specific AI Function requests, which aren't recorded there. To view their billed usage, see View costs for AI Function workloads. dbus is NULL for external rows and request_tags is NULL for hosted rows, because those sources don't record them.

Example queries​

Each query selects from the view and covers the last 30 days.

Spend by model, with model_source separating Databricks-hosted and external models:

SQL
SELECT
destination_model,
model_source,
SUM(usd) AS spend_usd
FROM <catalog>.<schema>.ai_gateway_spend
WHERE usage_date >= current_date() - INTERVAL 30 DAYS
GROUP BY destination_model, model_source
ORDER BY spend_usd DESC;

Spend by the user or Databricks service principal that issued the request:

SQL
SELECT
requester,
SUM(usd) AS spend_usd
FROM <catalog>.<schema>.ai_gateway_spend
WHERE requester IS NOT NULL
AND usage_date >= current_date() - INTERVAL 30 DAYS
GROUP BY requester
ORDER BY spend_usd DESC;

Spend by the team service tag:

SQL
SELECT
service_tags['team'] AS team,
SUM(usd) AS spend_usd
FROM <catalog>.<schema>.ai_gateway_spend
WHERE service_tags['team'] IS NOT NULL
AND usage_date >= current_date() - INTERVAL 30 DAYS
GROUP BY team
ORDER BY spend_usd DESC;

To group by request tag instead, replace service_tags with request_tags and add AND model_source = 'external', because request tags are recorded only for external model spend.

Build custom cost dashboards and reports​

Unity Gateway spend data lives in Unity Catalog system tables, so you can report on it with the same Databricks tools you use for the rest of your data, without exporting it to a separate cost tool:

  • Customize the usage dashboard: Add the charts and filters your teams need to the built-in dashboard. Save a copy first, because updating the dashboard to the latest template can overwrite your changes. See Built-in usage dashboard.
  • Combine spend with your own data: Join the combined spend view to tables your organization maintains, such as an HR directory, to see spend by department, cost center, or manager.
  • Control who sees what: Use Unity Catalog dynamic views and permissions so that each team or manager sees only their own spend.
  • Deliver reports on a schedule: Subscribe people or channels to dashboard updates by email, Slack, or Microsoft Teams. See Manage scheduled dashboard updates and subscriptions.

Report spend by department or cost center​

Unity Gateway attributes spend to users, models, and tags, but doesn't read your organization chart. To report by department, join the combined spend view to a user-to-department mapping your organization maintains, such as a Delta table synced from your HR system or identity provider. Replace <catalog>.<schema>.org_directory with your mapping table, which needs user_email and department columns.

SQL
SELECT
COALESCE(o.department, 'Unmapped') AS department,
SUM(s.usd) AS spend_usd
FROM <catalog>.<schema>.ai_gateway_spend s
LEFT JOIN <catalog>.<schema>.org_directory o
ON s.requester = o.user_email
WHERE s.usage_date >= current_date() - INTERVAL 30 DAYS
GROUP BY COALESCE(o.department, 'Unmapped')
ORDER BY spend_usd DESC;

The LEFT JOIN keeps spend from users who are missing from the mapping table in the totals, under an Unmapped bucket, instead of dropping it from the report.

Build a team spend dashboard for managers​

This isn't a built-in Unity Gateway feature. It uses Unity Catalog views and dashboards, plus a mapping table you maintain with user_email and manager_email columns.

  1. Create a view in a Unity Catalog schema that joins the combined spend view to your mapping table on the user email, and keeps only rows where the requester reports to the viewer. Use a dynamic view that filters on o.manager_email = current_user(), and allows full access to a finance or admin group with is_account_group_member.
  2. Grant managers SELECT on the view. Managers don't need access to the system tables.
  3. Build a dashboard on the view and share it with managers. To have each viewer's own identity applied, set the dashboard to use individual data permissions. See Dashboard data permissions.

Validate the view with a test manager account before you share the dashboard. Direct reports only appear if your mapping table contains them. For multi-level hierarchies, flatten the hierarchy in the mapping table.

To alert a manager when their team approaches a limit, send the team budget's threshold emails to the manager. See Configure alerts and usage blocking.

How spend is calculated​

Unity Gateway records spend regardless of where the model runs.

  • Databricks-hosted model spend is DBU usage in system.billing.usage, converted to list-price USD with system.billing.list_prices. It reflects list prices, not negotiated discounts or your final invoice. Unity Gateway enriches MODEL_SERVING billing records with service-specific metadata, so you can attribute cost to the associated services, target models, principals, and service tags. For the complete schema and field definitions, see the Billing usage system table reference.
  • External model spend is an estimate that Databricks computes for each request from its token usage and the external provider's published prices, aggregated hourly in system.ai_gateway.external_model_spend. See Limitations.
note

External model spend is provided for informational purposes only. These estimates might not reflect your final provider invoice, and Databricks is not liable for discrepancies in third-party billing.

For negotiated external pricing, configure a price multiplier on the model provider service.

Reference​

Billing usage fields​

Unity Gateway populates the following fields in system.billing.usage for both real-time and batch inference requests routed through it:

Field

Description

usage_metadata.ai_gateway.endpoint_name

The name of the Unity Gateway model service that received the request. This is the Unity Catalog fully qualified name, in the form <catalog>.<schema>.<modelservice>.

usage_metadata.ai_gateway.endpoint_id

The ID of the Unity Gateway model service.

usage_metadata.ai_gateway.destination_model

The destination model that handled the request, for example GPT-5.2.

usage_metadata.ai_gateway.destination_id

The ID of the target that handled the request.

identity_metadata.run_by

The user or Databricks service principal that issued the request.

custom_tags

Service tags configured on the Unity Gateway model service, such as team or cost_center.

Field

Description

usage_metadata.ai_gateway.endpoint_name

The name of the Unity Gateway model service that received the request. This is the Unity Catalog fully qualified name, in the form <catalog>.<schema>.<modelservice>.

usage_metadata.ai_gateway.endpoint_id

The ID of the Unity Gateway model service.

usage_metadata.ai_gateway.destination_model

The destination model that handled the request, for example GPT-5.2.

usage_metadata.ai_gateway.destination_id

The ID of the target that handled the request.

identity_metadata.run_by

The user or Databricks service principal that issued the request.

custom_tags

Service tags configured on the Unity Gateway model service, such as team or cost_center.

External model spend table schema​

The system.ai_gateway.external_model_spend table has the following schema:

Column name

Type

Description

record_id

STRING

A unique identifier for the aggregated spend record.

account_id

STRING

The account ID.

workspace_id

STRING

The ID of the workspace where the model provider service is configured.

usage_date

DATE

The date of the usage record, derived from usage_start_time.

usage_start_time

TIMESTAMP

The start of the hourly aggregation window, in UTC.

usage_end_time

TIMESTAMP

The end of the hourly aggregation window, in UTC.

ingestion_date

DATE

The date the record was ingested into the table.

usage_metadata

STRUCT

Metadata about the external model usage, including provider, model, endpoint_id, endpoint_name, destination_id, and destination_name.

custom_tags

STRUCT

User-provided tags for cost attribution, including endpoint_tags and request_tags.

usage_unit

STRING

The unit of measurement for usage_quantity. Always USD.

usage_quantity

DECIMAL

The estimated cost, in usage_unit, for the aggregation window.

pricing_metadata

STRUCT

Metadata about the pricing applied, including service_tier and long_context.

identity_metadata

STRUCT

Identity of the requester, including run_by and run_as.

Column name

Type

Description

record_id

STRING

A unique identifier for the aggregated spend record.

account_id

STRING

The account ID.

workspace_id

STRING

The ID of the workspace where the model provider service is configured.

usage_date

DATE

The date of the usage record, derived from usage_start_time.

usage_start_time

TIMESTAMP

The start of the hourly aggregation window, in UTC.

usage_end_time

TIMESTAMP

The end of the hourly aggregation window, in UTC.

ingestion_date

DATE

The date the record was ingested into the table.

usage_metadata

STRUCT

Metadata about the external model usage, including provider, model, endpoint_id, endpoint_name, destination_id, and destination_name.

custom_tags

STRUCT

User-provided tags for cost attribution, including endpoint_tags and request_tags.

usage_unit

STRING

The unit of measurement for usage_quantity. Always USD.

usage_quantity

DECIMAL

The estimated cost, in usage_unit, for the aggregation window.

pricing_metadata

STRUCT

Metadata about the pricing applied, including service_tier and long_context.

identity_metadata

STRUCT

Identity of the requester, including run_by and run_as.

Limitations​

  • Spend attribution for Databricks-hosted models applies to MODEL_SERVING records in system.billing.usage.
  • For model services with multiple destinations, such as traffic splitting or fallbacks, ai_gateway.destination_model and ai_gateway.destination_id identify the destination that ultimately served the request.
  • External model spend is supported only for model provider services in Unity Catalog.
  • External model spend tracking doesn't support the Custom provider. Databricks estimates spend from each provider's published prices, which are not available for custom endpoints.

Additional resources​