架构：

ACCOUNT_USAGE

CORTEX_AGENT_USAGE_HISTORY 视图

CORTEX_AGENT_USAGE_HISTORY 视图可用于查询 Cortex Agent 的使用历史记录。

备注

此视图不包括源自 Snowflake Intelligence 的请求。源自 Snowflake Intelligence 的请求记录在 SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY 视图中。

视图中的信息包括用户每次与 Cortex Agent 交互时消耗的 Credit 数量。一个请求会导致对底层工具（例如 Cortex Analyst 和 Cortex Search）的一次或多次调用。视图中的每一行都代表对代理的调用，并提供有关调用中汇总的令牌和 credit 的详细信息以及精细的详细信息。该视图还包括相关元数据，例如用户 ID、请求 ID 和代理 ID。有关 Cortex 计费的更多信息，请参阅 成本注意事项。

列

列名称

数据类型

描述

START_TIME

TIMESTAMP_LTZ

收到 Cortex Agent 消息请求的开始时间。

END_TIME

TIMESTAMP_LTZ

发送 Cortex Agent 消息响应的结束时间。

USER_ID

NUMBER

发起请求的用户的唯一标识符。

USER_NAME

VARCHAR

发起请求的用户的名称。

USER_TAGS

ARRAY

与用户关联的标签。数组中的每个对象都包含以下值对：

  • level：选择使用 时默认使用的角色和仓库。应用标签的级别（例如，“ACCOUNT”或“USER”）。

  • tag_database：选择使用 时默认使用的角色和仓库。定义标签的数据库。

  • tag_schema：选择使用 时默认使用的角色和仓库。定义标签的架构。

  • tag_name：选择使用 时默认使用的角色和仓库。标签的名称。

  • tag_value：选择使用 时默认使用的角色和仓库。标签的值。

REQUEST_ID

VARCHAR

请求的唯一标识符。

PARENT_REQUEST_ID

VARCHAR

父请求的标识符（如果适用）。

AGENT_DATABASE_ID

NUMBER

代理数据库的唯一标识符。

AGENT_DATABASE_NAME

VARCHAR

代理数据库的名称。

AGENT_SCHEMA_ID

NUMBER

代理架构的唯一标识符。

AGENT_SCHEMA_NAME

VARCHAR

代理架构的名称。

AGENT_ID

NUMBER

代理的唯一标识符。

AGENT_NAME

VARCHAR

代理的名称。

AGENT_TAGS

ARRAY

与代理关联的标签。数组中的每个对象都包含以下值对：

  • level：选择使用 时默认使用的角色和仓库。应用标签的级别（例如，“DATABASE”或“CORTEX_AGENT”）。

  • tag_database：选择使用 时默认使用的角色和仓库。定义标签的数据库。

  • tag_schema：选择使用 时默认使用的角色和仓库。定义标签的架构。

  • tag_name：选择使用 时默认使用的角色和仓库。标签的名称。

  • tag_value：选择使用 时默认使用的角色和仓库。标签的值。

TOKEN_CREDITS

NUMBER

请求使用的词元 Credit 数量。用于用户级预算管理。

TOKENS

NUMBER

Cortex Agent 使用的令牌总和。

TOKENS_GRANULAR

ARRAY

按请求、服务类型（cortex_agents、cortex_analyst）和模型提供令牌使用量细分。包括每个模型的输入、cache_read_input、cache_write_input 和输出词元计数。当定价数据中不存在模型时，使用“unknown”作为模型名称。数组中的每个对象都包含以下值对：

  • request_id：选择使用 时默认使用的角色和仓库。请求的唯一标识符。

  • service_type：选择使用 时默认使用的角色和仓库。服务类型，例如“cortex_agents”或“cortex_analyst”。

  • model：选择使用 时默认使用的角色和仓库。用于请求的模型名称。

  • input：选择使用 时默认使用的角色和仓库。输入词元的数量。

  • cache_read_input：选择使用 时默认使用的角色和仓库。缓存读取输入词元的数量。

  • cache_write_input：选择使用 时默认使用的角色和仓库。缓存写入输入词元的数量。

  • output：选择使用 时默认使用的角色和仓库。输出词元的数量。

  • start_time：选择使用 时默认使用的角色和仓库。请求的开始时间。

CREDITS_GRANULAR

ARRAY

按请求、服务类型（cortex_agents、cortex_analyst）和模型提供 credit 使用量细分。包括每个模型的输入、cache_read_input、cache_write_input 和输出 credit 值。当定价数据中不存在模型时，使用“unknown”作为模型名称。数组中的每个对象都包含以下值对：

  • request_id：选择使用 时默认使用的角色和仓库。请求的唯一标识符。

  • service_type：选择使用 时默认使用的角色和仓库。服务类型，例如“cortex_agents”或“cortex_analyst”。

  • model：选择使用 时默认使用的角色和仓库。用于请求的模型名称。

  • input：选择使用 时默认使用的角色和仓库。输入词元的 Credit 值。

  • cache_read_input：选择使用 时默认使用的角色和仓库。缓存读取输入词元的 Credit 值。

  • cache_write_input：选择使用 时默认使用的角色和仓库。缓存写入输入词元的 Credit 值。

  • output：选择使用 时默认使用的角色和仓库。输出词元的 Credit 值。

  • start_time：选择使用 时默认使用的角色和仓库。请求的开始时间。

METADATA

OBJECT

保留以供其他元数据使用。目前为空。

示例

检索 Cortex Agent 使用历史记录：

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