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.

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;
Copy
+-------------------------------+-------------------------------+---------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+-------------------+-------------------+---------------------+-----------------+-------------------+----------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| 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"}}] | {}       |
+-------------------------------+-------------------------------+---------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+-------------------+-------------------+---------------------+-----------------+-------------------+----------+------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+