跳转到主要内容
GET
/
api
/
v2alpha
/
analytics
/
active-users
获取活跃用户分析
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/active-users \
  --header 'Authorization: Bearer <token>'
{ "data": [ { "active_users": 142 } ], "pagination": { "next_page_cursor": null }, "metadata": { "data_freshness": "2026-01-16T03:00:00.000Z", "query_time_ms": 612, "team_id": "team_abc123" } }
这是一个v2 端点，使用 Bearer 令牌进行身份验证和查询参数；不同于 v1 分析 API，后者在请求体中使用服务密钥。请参阅下方的 身份验证。
此端点不适用于实时用量监控。数据按小时聚合，且 速率限制较低 (每个团队每小时 10 个请求) 。请将其用于定期报告和批量导出。

​
身份验证

此端点使用 Bearer 令牌 进行身份验证。请在 Authorization 标头中包含你的服务密钥： 
Authorization: Bearer <your_service_key>
服务密钥必须具备 Analytics Read 权限。可在团队设置中的 “Service Keys” 下创建一个。

​
什么情况下会计为活跃用户

如果某个用户在给定时间段内有任何计费事件，则会被计为活跃。active_users 字段表示不同用户的数量。

​
分组与粒度

使用 granularity 和 group_by 控制返回数据的结构：
  • 不设置粒度或分组 — 返回单行数据，其中包含整个日期范围内的活跃用户总数
  • granularity=daily — 每行都包含一个 YYYY-MM-DD 格式的 timestamp (日活跃用户)
  • granularity=monthly — 每行都包含一个 YYYY-MM 格式的 timestamp (月活跃用户)
  • group_by=user — 每个活跃用户返回一行，并包含 user_id；每行的 active_users 都为 1
与 获取用量 不同，活跃用户端点的 group_by 仅支持 user。其他维度 (model_uid、ide) 在此处无效。
结果将按分页返回，默认页面大小为 1,000 行 (最大 10,000 行) 。当有更多结果时， 响应会在 pagination 对象中包含一个 next_page_cursor。将其作为 page_cursor 查询 参数传入，以获取下一页。 页面游标会在 24 小时后过期。后续的分页请求不会作为新的查询计入你的速率限制。

​
缓存

响应中包含一个 ETag 标头。为避免重复传输数据，请在请求中附带之前的 ETag 值作为 If-None-Match 标头；如果数据未发生变化，服务器将返回 304 Not Modified。

​
速率限制

此端点按团队限制为每小时 10 次请求。如果你超出此限制， 服务器会返回 429 Too Many Requests，并附带 Retry-After 标头。 对先前查询结果进行分页 (沿用 next_page_cursor) 不会计入此限制—— 只有每份报告的初始查询才会计入。较低的限制说明，此端点用于 定期报告，而非实时用量监控。

授权

​
Authorization
string
header
必填

需要一个具有 Analytics Read 权限的服务密钥，并通过 Authorization 标头以 Bearer 令牌的形式传递。

你可以在团队设置中的“Service Keys”部分创建服务密钥。

请求头

​
If-None-Match
string

来自上一个响应的 ETag 值。如果数据未发生变化，服务器将返回 304 Not Modified。

查询参数

​
start_date
string<date>
必填

日期范围的开始日期（含），格式为 YYYY-MM-DD。

​
end_date
string<date>
必填

日期范围的结束日期（含），格式为 YYYY-MM-DD。范围不得超过 90 天。

​
product
enum<string>
必填

要查询活跃用户数的产品。

可用选项:
agent
​
granularity
enum<string>

用于对结果分组的时间粒度。指定后，每一行都包含 timestamp 字段。 如果省略，活跃用户数会在整个日期范围内聚合。

可用选项:
daily,
monthly
​
group_by
enum<string>

用于对结果分组的维度。活跃用户端点仅支持 user，这会为每个活跃用户返回一行 （每行的 active_users = 1）。

可用选项:
user
​
models
string

用于筛选结果的模型 UID 逗号分隔列表。

​
group_id
string

将结果筛选为特定组中的用户。服务密钥必须具有该组的访问权限。

​
user_id
string

将结果筛选为特定用户（auth UID）。

​
page_size
integer
默认值:1000

每页返回的最大行数。

必填范围: 1 <= x <= 10000
​
page_cursor
string

来自上一个响应中 pagination.next_page_cursor 的不透明游标，用于获取下一页。

响应

活跃用户数据已成功返回。

​
data
object[]
必填

活跃用户数据行数组。

​
pagination
object
必填
​
metadata
object
必填