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.
Exigences
- Unity Gateway activé pour votre compte.
- Un workspace Databricks dans une région prise en charge par Unity Gateway.
- La table système d'utilisation facturable activée pour votre compte. Consultez Activer les tables système.
- Access to the Unity Gateway system tables. See Grant access to system tables.
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:
system.billing.usage: Databricks-hosted model spend, in Databricks units (DBUs). See Billing usage fields.system.ai_gateway.external_model_spend: Estimated spend for external models, in USD. See External model spend table schema.
View spend in the usage dashboard
Le tableau de bord d’utilisation intégré de Unity Gateway vous aide à identifier les tendances de dépenses, à comparer les modèles et les utilisateurs, et à affecter les dépenses aux équipes et aux projets. Il comprend les dépenses liées aux modèles hébergés par Databricks et les dépenses estimées liées aux modèles externes.
Ouvrez Unity Gateway > Gouvernance > Tableau de bord d’utilisation .

- Vue d’ensemble : comparez les dépenses du modèle et de l’utilisateur, suivez les modifications et évaluez les dépenses moyennes par million de jetons ou par requête.
- 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.
- Sessions d’agent de codage : examinez les sessions à forte dépense dans le Agents de codage tab, avec une estimation des dépenses de session ainsi que l’utilisation des jetons, les modèles et l’activité des sous-agents.
Consultez le Tableau de bord d'utilisation intégré pour configurer et mettre à jour le tableau de bord d'utilisation.
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:
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.
- Ouvrez Unity Gateway > Gouvernance > Tableau de bord d’utilisation .
- Click Ask Genie .
- Ask your question in plain language. For example:
- Which users spent the most in the last 30 days?
- What did the
ml-platformteam 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:
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:
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:
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:
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.
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.
- 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 withis_account_group_member. - Grant managers
SELECTon the view. Managers don't need access to the system tables. - 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 withsystem.billing.list_prices. It reflects list prices, not negotiated discounts or your final invoice. Unity Gateway enrichesMODEL_SERVINGbilling 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.
Le coût des modèles externes est fourni à titre indicatif uniquement. Ces estimations peuvent ne pas refléter la facture finale de votre prestataire, et Databricks décline toute responsabilité en cas d’écarts dans la facturation effectuée par des tiers.
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:
Champ | Description |
|---|---|
| Le nom du service de modèle Unity Gateway qui a reçu la requête. Il s'agit du nom entièrement qualifié Unity Catalog, sous la forme |
| L'ID du service de modèle Unity Gateway. |
| Le modèle de destination qui a géré la requête, par exemple |
| L'ID de la cible qui a traité la requête. |
| L'utilisateur ou le Service Principal Databricks qui a émis la requête. |
| Tags de service configurés sur le service de modèle Unity Gateway, tels que |
External model spend table schema
La table system.ai_gateway.external_model_spend a le schéma suivant :
Nom de colonne | Type | Description |
|---|---|---|
| CHAÎNE | Un identifiant unique pour l'enregistrement des dépenses agrégées. |
| CHAÎNE | L'ID du compte. |
| CHAÎNE | L'identifiant du Workspace où le service de fournisseur de modèle est configuré. |
| Date | La date de l'enregistrement d'utilisation, dérivée de |
| Horodatage | Le start de la fenêtre d'agrégation horaire, en UTC. |
| Horodatage | Fin de la fenêtre d'agrégation horaire, en UTC. |
| Date | La date à laquelle l'enregistrement a été ingéré dans la table. |
| Structure | Métadonnées relatives à l'utilisation du modèle externe, y compris |
| Structure | Étiquettes fournies par l'utilisateur pour l'attribution des coûts, y compris |
| CHAÎNE | L'unité de mesure pour |
| DÉCIMAL | Le coût estimé, en |
| Structure | Métadonnées sur les Tarifs appliqués, y compris |
| Structure | Identité du demandeur, y compris |
Limitations
- L'attribution des dépenses pour les modèles hébergés par Databricks s'applique à
MODEL_SERVINGenregistrements danssystem.billing.usage. - Pour les services de modèles avec plusieurs destinations, tels que la répartition du trafic ou les fallbacks,
ai_gateway.destination_modeletai_gateway.destination_ididentifient la destination qui a finalement servi la requête. - La dépense de modèle externe n'est prise en charge que pour les services de fournisseur de modèles dans 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.