Schema:: ACCOUNT_USAGE

CORTEX_AGENT_USAGE_HISTORY view¶

The CORTEX_AGENT_USAGE_HISTORY view can be used to query the usage history of Cortex Agents.

Note

This view does not include requests originating from Snowflake Intelligence. Requests originating from Snowflake Intelligence are recorded in the SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY view.

The information in the view includes the number of credits consumed each time a user interacts with Cortex Agents. A request results in one or more calls to underlying tools, for example, Cortex Analyst and Cortex Search. Each row in the view represents a call to the agent and provides detail about the aggregated tokens and credits in the call as well as granular detail. The view also includes relevant metadata, such as the user ID, request ID, and the agent ID. For more information about Cortex billing, see Cost considerations.

Columns¶


Column name	Data type	Description
START_TIME	TIMESTAMP_LTZ	Start time when the Cortex Agent message request was received.
END_TIME	TIMESTAMP_LTZ	End time when the Cortex Agent message response was sent.
USER_ID	NUMBER	The unique identifier of the user who made the request.
USER_NAME	VARCHAR	The name of the user who made the request.
USER_TAGS	ARRAY	Tags associated with the user. Each object in the array contains the following value pairs: `level`: The level at which the tag is applied (for example, “ACCOUNT” or “USER”). `tag_database`: The database where the tag is defined. `tag_schema`: The schema where the tag is defined. `tag_name`: The name of the tag. `tag_value`: The value of the tag.
REQUEST_ID	VARCHAR	The unique identifier for the request.
PARENT_REQUEST_ID	VARCHAR	The identifier of the parent request, if applicable.
AGENT_DATABASE_ID	NUMBER	The unique identifier of the agent database.
AGENT_DATABASE_NAME	VARCHAR	The name of the agent database.
AGENT_SCHEMA_ID	NUMBER	The unique identifier of the agent schema.
AGENT_SCHEMA_NAME	VARCHAR	The name of the agent schema.
AGENT_ID	NUMBER	The unique identifier of the agent.
AGENT_NAME	VARCHAR	The name of the agent.
AGENT_TAGS	ARRAY	Tags associated with the Agent. Each object in the array contains the following value pairs: `level`: The level at which the tag is applied (for example, “DATABASE” or “CORTEX_AGENT”). `tag_database`: The database where the tag is defined. `tag_schema`: The schema where the tag is defined. `tag_name`: The name of the tag. `tag_value`: The value of the tag.
TOKEN_CREDITS	NUMBER	The number of token credits used for the request. Used for user-level budgeting.
TOKENS	NUMBER	Sum of the tokens used by the Cortex Agent.
TOKENS_GRANULAR	ARRAY	Granular breakdown of token usage by request, service type (cortex_agents, cortex_analyst), and model. Includes input, cache_read_input, cache_write_input, and output token counts per model. The “unknown” model name is used when a model is not present in the pricing data. Each object in the array contains the following value pairs: `request_id`: The unique identifier for the request. `service_type`: The service type, such as “cortex_agents” or “cortex_analyst”. `model`: The model name used for the request. `input`: Number of input tokens. `cache_read_input`: Number of cache read input tokens. `cache_write_input`: Number of cache write input tokens. `output`: Number of output tokens. `start_time`: The start time of the request.
CREDITS_GRANULAR	ARRAY	Granular breakdown of credit usage by request, service type (cortex_agents, cortex_analyst), and model. Includes input, cache_read_input, cache_write_input, and output credit values per model. The “unknown” model name is used when a model is not present in the pricing data. Each object in the array contains the following value pairs: `request_id`: The unique identifier for the request. `service_type`: The service type, such as “cortex_agents” or “cortex_analyst”. `model`: The model name used for the request. `input`: Credit value for input tokens. `cache_read_input`: Credit value for cache read input tokens. `cache_write_input`: Credit value for cache write input tokens. `output`: Credit value for output tokens. `start_time`: The start time of the request.
METADATA	OBJECT	Reserved for additional metadata. Currently empty.

Examples¶

Retrieve Cortex Agent usage history:

SELECT *
  FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY;

+-------------------------------+-------------------------------+---------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+-------------------+-------------------+---------------------+-----------------+-------------------+----------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| START_TIME                    | END_TIME                      | USER_ID | USER_NAME | USER_TAGS                                                                                                                                                                                                                                                | REQUEST_ID                           | PARENT_REQUEST_ID | AGENT_DATABASE_ID | AGENT_DATABASE_NAME | AGENT_SCHEMA_ID | AGENT_SCHEMA_NAME | AGENT_ID | AGENT_NAME | AGENT_TAGS                                                                                                                                                                                                                                                | TOKEN_CREDITS | TOKENS | TOKENS_GRANULAR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | CREDITS_GRANULAR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | METADATA |
|-------------------------------+-------------------------------+---------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+-------------------+-------------------+---------------------+-----------------+-------------------+----------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------|
| 2026-02-06 10:11:51.642 +0000 | 2026-02-06 10:11:55.932 +0000 | 42563   | JKOWAL    | [{"level": "ACCOUNT", "tag_database": "SI", "tag_schema": "AGENTS", "tag_name": "cost-center", "tag_value": "engineering"}, {"level": "USER", "tag_database": "FINANCE", "tag_schema": "AGENTS", "tag_name": "cost-center", "tag_value": "engineering"}] | 5caf3de3-86b2-4896-b706-9f2d7629d337 | NULL              | 234               | finance             | 4231            | analytics         | 9234     | agent1     | [{"level": "DATABASE", "tag_database": "SI", "tag_schema": "AGENTS", "tag_name": "cost-center", "tag_value": "finance"}, {"level": "CORTEX_AGENT", "tag_database": "FINANCE", "tag_schema": "AGENTS", "tag_name": "cost-center", "tag_value": "finance"}] | 20.000000000  | 1900   | [{"5caf3de3-86b2-4896-b706-9f2d7629d337": {"cortex_agents": {"modelX": {"input": 100, "cache_read_input": 300, "cache_write_input": 400, "output": 200}}, "start_time": "2026-02-06 10:11:51.642 +0000"}}, {"a98b2946-4a7d-4028-9b19-1dab89fbf6c7": {"cortex_analyst": {"modelY": {"input": 100, "output": 200}, "modelZ": {"input": 100, "output": 200}}, "start_time": "2026-02-06 10:11:52.313 +0000"}}, {"996abb8b-678a-440d-9061-d186b6acc91b": {"cortex_analyst": {"unknown": {"input": 100, "output": 200}}, "start_time": "2026-02-06 10:11:53.112 +0000"}}] | [{"5caf3de3-86b2-4896-b706-9f2d7629d337": {"cortex_agents": {"modelX": {"input": 1, "cache_read_input": 2, "cache_write_input": 3, "output": 4}}, "start_time": "2026-02-06 10:11:51.642 +0000"}}, {"a98b2946-4a7d-4028-9b19-1dab89fbf6c7": {"cortex_analyst": {"modelY": {"input": 1, "output": 4}, "modelZ": {"input": 1, "output": 4}}, "start_time": "2026-02-06 10:11:52.313 +0000"}}, {"996abb8b-678a-440d-9061-d186b6acc91b": {"cortex_analyst": {"unknown": {"input": 0, "output": 0}}, "start_time": "2026-02-06 10:11:53.112 +0000"}}] | {}       |
+-------------------------------+-------------------------------+---------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+-------------------+-------------------+---------------------+-----------------+-------------------+----------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+