Track model usage
Monitor usage for Unity Gateway services with the system.ai_gateway.usage system table. It captures requests to model services, model provider services, and MCP services from various sources, including AI Query, coding agents, Databricks Apps, AI Playground, and other applications.
Usage records include requester and service details, response status, model token usage and latency, MCP call metadata, and coding-agent session metadata. Query the table for custom analysis, or use the built-in usage dashboard to monitor usage, spend, adoption, and performance.
Account and workspace admins can also view a consolidated overview of AI usage on the AI page in Governance Hub.
Requirements
- A Databricks workspace in a Unity Gateway supported region.
- Unity Catalog enabled for your workspace. See Enable a workspace for Unity Catalog.
- Both account and metastore admin roles are required to view or query the
system.ai_gateway.usagetable by default. Admins can manage access to system tables to control permissions for users, groups, and service principals.
Query the usage table
Unity Gateway logs usage data to the system.ai_gateway.usage system table. You can view the table in the UI, or query the table from Databricks SQL or a notebook.
Records are typically available within one hour. Data delivery for new workspaces can take longer than this.
To view the table in the UI, click the usage tracking table link on the model service page to open the table in Catalog Explorer.
To query the table from Databricks SQL or a notebook:
SELECT * FROM system.ai_gateway.usage;
Genie Code can do this for you. Try this example prompt:
Query the system.ai_gateway.usage table to analyze AI Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.
Pricing
Usage tracking is a billed Unity Gateway feature. Databricks charges for the usage that it logs to the system.ai_gateway.usage table. See Unity Gateway pricing.
Built-in usage dashboard
The built-in Unity Gateway usage dashboard provides a consolidated view of usage, spend, adoption, and performance across models, MCP services, coding agents, and skills.
Create the dashboard
Account admins can create the dashboard from the Unity Gateway page:
- Click Govern > Create Usage Dashboard.
- Choose Account usage to analyze usage across workspaces, or Workspace usage to restrict analysis to the current workspace.
- Configure Data permissions:
- Share data permission: Viewers run dashboard queries using your data permissions.
- Individual data permission: Each viewer runs dashboard queries using their own data permissions.
- Choose whether to enable Automatic updates and Scheduled data refresh.
- Click Setup & publish.
The default SQL warehouse is selected automatically. The identity running dashboard queries needs access to the underlying system tables. See Grant access to system tables and Dashboard data permissions.
In workspaces without the Govern dropdown, use the standalone Create Dashboard, View Dashboard, and Update buttons on the Unity Gateway page.
Explore the dashboard
Click Govern > Usage Dashboard to open the dashboard in a new tab.
Tab | Analysis |
|---|---|
Overview | Review usage, tokens, active users, and coding-agent sessions. Compare models and users by spend, spend trends, and spend per token or request. |
Spend | Analyze spend by model and user, compare token consumption and caching, and attribute spend through service and request tags. |
Coding Agents | Compare agent adoption, harness usage, sessions, token consumption, and subagents. Investigate individual sessions ranked by estimated spend. |
MCPs | Track tool calls and active users, identify frequently used services and tools, and compare usage sources. |
Skills | Track skill downloads and loads, compare skill adoption, and review activity by user. |
Performance | Compare model and MCP latency, streaming time to first byte, output tokens/sec, cache hit rates, errors, and rate-limited calls. |
README | Review dashboard capabilities, recent changes, and links to the underlying data sources. |
Select a date range to focus the analysis, or select a Service Tag Key and one or more Service Tag Value entries to narrow usage and spend to specific teams or projects. Account-scoped dashboards also include a Workspace ID filter. Service-tag filters do not apply to the Skills tab.
Update the dashboard
When a newer dashboard version is available, an account admin can click Update on the dashboard version row in the Govern dropdown. With Automatic updates enabled, a newer template is applied when an account admin visits the Unity Gateway page.
Updating replaces the dashboard content with the latest template and can overwrite customizations. Save a copy before updating if you want to preserve your changes.
Refresh dashboard data
Scheduled data refresh refreshes query results every six hours.
Manage the refresh schedule in the dashboard. See Create a schedule.
Usage table schema
The system.ai_gateway.usage table has the following schema:
Column name | Type | Description | Example |
|---|---|---|---|
| STRING | The account ID. |
|
| STRING | The workspace ID. |
|
| STRING | A unique identifier for the request. |
|
| STRING | A unique identifier for each individual inference call. Multiple invocations can share the same |
|
| INTEGER | The schema version of the usage record. |
|
| STRING | The type of service that generated the usage record. Values are |
|
| STRING | The ID of the Model Service, MCP Service, or Model Provider Service. |
|
| STRING | The Unity Catalog fully qualified name of the service. |
|
| MAP | Resource tags applied to the Unity Catalog securable at creation or update time. They apply to all requests to the service and are useful for categorizing usage by team, cost center, or project. |
|
| STRING | The unique ID of the Unity Gateway model service. |
|
| STRING | The name of the Unity Gateway model service. |
|
| MAP | Tags configured on the model service at creation or update time. They apply to all requests to the model service and are useful for categorizing services by team, cost center, or project. |
|
| STRUCT | Model service metadata including |
|
| TIMESTAMP | The timestamp when the request was received. |
|
| LONG | The total latency in milliseconds. |
|
| LONG | The time to first byte in milliseconds. |
|
| STRING | The type of destination (for example, external model or foundation model). |
|
| STRING | The name of the destination model or provider. |
|
| STRING | The unique ID of the destination. |
|
| STRING | The specific model used for the request. |
|
| STRING | The ID of the user or service principal that made the request. |
|
| STRING | The type of requester (user, service principal, or user group). |
|
| STRING | The IP address of the requester. |
|
| STRING | The URL of the request. |
|
| STRING | The user agent of the requester. |
|
| STRING | The type of API call (for example, chat, completions, or embeddings). |
|
| MAP | User-provided tags sent with individual requests using the |
|
| STRUCT | Information about where the request originated, the service tier reported by the model provider, and whether the request used a Claude subscription. |
|
| LONG | The number of input tokens. |
|
| LONG | The number of output tokens. |
|
| LONG | The total number of tokens (input + output). |
|
| STRUCT | Detailed token and tool usage breakdown, including |
|
| STRING | The content type of the response. |
|
| INT | The HTTP status code of the response. |
|
| STRUCT | Routing details for fallback attempts. Contains an |
|
| STRUCT | Details of a request to an MCP service, including the tool invoked, the server type, and the JSON-RPC operation. Populated for |
|
| STRUCT | Session and client context, including session and subagent IDs, coding agent name and version, client interface, reasoning effort, and smart-routing recipe. Use these fields to group related requests and analyze usage by agent or session. |
|
| STRING | The Databricks credential type used to authenticate the request: a personal access token ( |
|
Nested column schemas
The following tables describe fields within nested STRUCT columns. Field availability depends on the service, model, and client used for the request.
Invocation and token metadata
Field path | Type | Description |
|---|---|---|
| STRING | The application, service, or API that initiated the request. Use this field to attribute usage to its source. Values include |
| STRING | The service tier reported by the model provider in the inference response, such as |
| BOOLEAN | Whether the request was relayed to Anthropic using the caller's Claude subscription. |
| LONG | The number of tokens read from the prompt cache. |
| LONG | The number of tokens written to the prompt cache. |
| LONG | The number of reasoning tokens in the output. |
| LONG | The number of input tokens written to the prompt cache with a 5-minute lifetime. |
| LONG | The number of input tokens written to the prompt cache with a 1-hour lifetime. |
| LONG | The number of file search tool calls made as part of the request. |
| LONG | The number of billable web search queries made as part of the request. |
MCP service metadata
These fields are populated in mcp_metadata for MCP_SERVICE rows.
Field path | Type | Description |
|---|---|---|
| STRING | The name of the tool invoked by an MCP |
| STRING | The category of MCP server handling the request, such as |
| STRING | The JSON-RPC operation requested by the client, such as |
Session metadata
The session_metadata fields help correlate requests within a session and distinguish coding agents, client interfaces, and request settings. Each field is populated when the corresponding information is available from the client or request.
Field path | Type | Description |
|---|---|---|
| STRING | The session ID provided by the client. Use it to group requests made during the same conversation or coding-agent session. |
| STRING | The subagent ID provided by the client. Use it with |
| STRING | The normalized name of the coding agent that sent the request, such as |
| STRING | The coding agent's reported version. Use it with |
| STRING | The client interface from which the coding agent sent the request, such as a command-line interface, IDE, or desktop application. |
| STRING | The reasoning effort specified in the request, such as |
| STRING | The name of the smart-routing recipe selected by the client. Use it to group usage by routing recipe. |
Tag requests for usage tracking
Request tags are custom key-value pairs that the caller attaches to individual requests. Use request tags to attribute usage by project, team, environment, end user, or any other dimension relevant to your organization. Request tags are logged to the system.ai_gateway.usage table and can be used to filter, aggregate, and analyze usage data.
To tag individual requests, include the Databricks-Ai-Gateway-Request-Tags HTTP header with a JSON object mapping string keys to string values. Request tags are logged to the request_tags column in the usage table and in inference tables.
For examples showing how to set request tags with REST API, OpenAI SDK, and Anthropic SDK, see Request tagging.
For example, you can aggregate usage by project using request tags:
SELECT
request_tags['project'] AS project,
COUNT(*) AS request_count,
SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE request_tags['project'] IS NOT NULL
GROUP BY request_tags['project']
ORDER BY total_tokens DESC;
Limitations
- Unity Gateway doesn't track token usage for non-streaming, non-embedding responses larger than 1 MiB.