# 事件分析报表 > 来源：https://help.gravity-engine.com/docs/server-integration/reporting/event-analysis-reports > 说明如何通过 Gravity Engine OpenAPI 查询事件分析结果及其时间粒度、指标和筛选条件，涵盖认证、请求参数、筛选条件和返回字段。 此接口用于获取引力收集到的用户事件分析数据，支持按时间颗粒度聚合、多维度分组及自定义查询指标。 **数据更新频率：** 数据分钟级更新延迟，高峰期时间可能会变长，极端情况可能会延迟 10 分钟以上。 *** ## 申请引力开发者应用 [#申请引力开发者应用] 在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。 创建好开发者应用之后，请复制 `app_key` 参数，并发送给研发同学以供后续接口调用使用。 *** ## 接口限频 [#接口限频] 默认接口限频：每 10 秒 10 次。接口限频按开发者应用维度统计，即同一个 `app_key` 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。 *** ## 接口信息 [#接口信息] ### 请求地址 [#请求地址] ```text https://api-insight.gravity-engine.com/openapi/api/v1/report/events/list/ ``` ### 请求方法 [#请求方法] POST ### Header [#header] | 字段 | 类型 | 描述 | | ------------- | ------ | ------------------------------------------------------------- | | Authorization | string | 具体如何生成，请参考 [【签名生成】](/docs/server-integration/request-signing) | *** ## Body 请求参数 [#body-请求参数] | 字段 | 必填 | 参数类型 | 描述 | | ------------------------ | -- | ------------------------ | ----------------------------------------------------------------------------------- | | `app_id` | Y | number | 查询的应用引力 ID，可以在引力后台-[应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面获取 | | `event_date_list` | Y | string\[] | 事件发生时间区间。例如 `["2026-06-25 00:00:00", "2026-07-01 23:59:59"]`，数组长度必须为 2，区间范围不超过 31 天 | | `time_scale` | Y | string | 查询时间颗粒度。具体取值参见 [time\_scale 枚举](#time-scale-枚举) | | `query_item_list` | Y | QueryItemObject\[] | 查询指标列表。具体参见 [QueryItemObject](#queryitemobject) | | `custom_query_item_list` | N | CustomQueryObject\[] | 自定义公式查询列表。具体参见 [CustomQueryObject](#customqueryobject) | | `global_conditions` | N | GlobalConditionObject\[] | 全局过滤条件数组。具体参见 [GlobalConditionObject](#globalconditionobject) | | `global_cond_logic` | N | string | 全局过滤条件逻辑。`AND`（默认）或 `OR` | | `group_by_list` | N | GroupByObject\[] | 分组维度列表。具体参见 [GroupByObject](#groupbyobject) | | `aggregate_config` | N | AggregateConfigObject | 聚合配置。具体参见 [AggregateConfigObject](#aggregateconfigobject) | | `extra_data` | N | ExtraDataObject | 附加配置。具体参见 [ExtraDataObject](#extradataobject) | | `sign` | Y | string | 签名。详情请参考 [【签名生成】](/docs/server-integration/request-signing) | ### time\_scale 枚举 [#time_scale-枚举] | 值 | 说明 | | -------- | ----------- | | `minute` | 按分钟聚合 | | `hour` | 按小时聚合 | | `day` | 按天聚合 | | `week` | 按周聚合 | | `month` | 按月聚合 | | `total` | 汇总（不拆分时间维度） | *** ## QueryItemObject [#queryitemobject] 查询指标对象，用于描述需要统计的事件及指标。 | 字段 | 必填 | 参数类型 | 描述 | | ------------- | -- | ------------ | ---------------------------------------------------------------------------------------------------- | | `event_name` | Y | string | 事件名，如 `$UserWithdraw`，具体的事件名称请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) | | `event_label` | N | string | 事件显示名称，如 `用户提现` | | `custom_name` | N | string | 自定义指标名称，如 `用户提现.总次数` | | `target` | Y | TargetObject | 统计目标，具体参见 [TargetObject](#targetobject) | | `conditions` | Y | object\[] | 事件过滤条件列表。同 [GlobalConditionObject](#globalconditionobject) | | `cond_logic` | N | string | 事件过滤条件逻辑，`AND`（默认）或 `OR` | | `event_index` | N | number | 事件序号，从 0 开始，用于标识响应中对应的事件 | ### TargetObject [#targetobject] | 字段 | 必填 | 参数类型 | 描述 | | ------- | -- | ------ | ------------------------------------------------------------------------------ | | `name` | Y | string | 指标名称。预置指标：`PresetAllCount`（总次数）、`PresetUserCount`（触发用户数）、`PresetUserAvg`（人均次数） | | `field` | Y | string | 预置指标字段。与 `name` 保持一致（如果不是预置指标，则传入事件属性（event properties）名称） | #### 非预置指标说明 [#非预置指标说明] | 中文名称 | 英文名称 | | ---------------------------------- | -------------------------- | | 文本 / 布尔值 / 时间 / 日期 类型 `field` 指标适用 | | | 去重数 | `DistinctCount` | | 列表（list）类型 `field` 指标适用 | | | 列表去重数 | `ListDistinctCount` | | 集合去重数 | `ListSetDistinctCount` | | 元素去重数 | `ListElementDistinctCount` | | 整数 / 浮点数 类型 `field` 指标适用 | | | 总和 | `SumCount` | | 最大数 | `MaxCount` | | 最小数 | `MinCount` | | 去重数 | `DistinctCount` | | 人均值 | `UserAvg` | | 均值 | `ValueAvg` | | 标准差 | `StdDev` | | 方差 | `VarSamp` | | 中位数 | `Median` | | 99 分位数 | `Quantile_99` | | 95 分位数 | `Quantile_95` | | 90 分位数 | `Quantile_90` | | 80 分位数 | `Quantile_80` | | 75 分位数 | `Quantile_75` | | 70 分位数 | `Quantile_70` | | 60 分位数 | `Quantile_60` | | 40 分位数 | `Quantile_40` | | 30 分位数 | `Quantile_30` | | 25 分位数 | `Quantile_25` | | 20 分位数 | `Quantile_20` | | 10 分位数 | `Quantile_10` | | 5 分位数 | `Quantile_5` | ### query\_item\_list 示例 [#query_item_list-示例] ```json [ { "event_name": "$UserWithdraw", "event_label": "用户提现", "custom_name": "用户提现.总次数", "target": { "name": "PresetAllCount", "field": "PresetAllCount" }, "conditions": [ { "operator": "RANGE_IN", "field": "create_date_list", "type": "default_user", "value": [ "2026-07-01 00:00:00", "2026-07-02 23:59:59" ] } ], "cond_logic": "AND", "event_index": 0 } ] ``` *** ## CustomQueryObject [#customqueryobject] | 字段 | 必填 | 参数类型 | 描述 | | ----------------- | -- | ------------------ | ------------------------------------------------------------------ | | `custom_name` | Y | string | 自定义公式名称。 | | `formula` | Y | string | 公式。如 `x/x`（x 代表指标，即「指标/指标」）、`x/100`（指标除以常量），其他同理 | | `query_item_list` | Y | QueryItemObject\[] | 同 [QueryItemObject](#queryitemobject) | | `decimal_point` | N | string | 保留小数。默认 `two_point`（两位小数）、`three_point`（3 位小数）、`four_point`（4 位小数） | | `event_index` | Y | int | 指标返回序列 ID | ## GlobalConditionObject [#globalconditionobject] 全局过滤条件对象，用于对用户属性或事件属性进行筛选。 | 字段 | 必填 | 参数类型 | 描述 | | ---------- | -- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `field` | Y | string | 过滤字段名。用户默认属性/再归因属性支持的过滤字段见下表；事件属性的具体字段参见 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 的事件属性；用户属性的具体字段参见 [元数据-用户属性](https://web.gravity-engine.com/#/manage/metadata/userProperty) | | `type` | Y | string | 字段类型，例如 `default_user`（用户默认属性）、`user`（用户属性）、`user_re_attribute`（用户再归因属性）、`event`（事件属性） | | `operator` | Y | string | 查询操作符，支持的操作符参见 [【操作符说明】](/docs/appendix/multidimensional-report-fields#%E6%93%8D%E4%BD%9C%E7%AC%A6%E8%AF%B4%E6%98%8Eoperator) | | `value` | Y | string\[] | 过滤值数组 | ### 用户默认属性/再归因属性支持的过滤字段 [#用户默认属性再归因属性支持的过滤字段] | 字段 | type | 必填 | 参数类型 | 描述 | | -------------------------- | ------------------- | -- | --------- | ----------- | | `$UserCreateTime` | `default_user` | N | string\[] | 用户注册时间 | | `$PresetModifyTime` | `default_user` | N | string\[] | 更新时间 | | `$PresetLatestLoginDay` | `default_user` | N | string\[] | 最近活跃时间 | | `$PresetUserAid` | `default_user` | N | string\[] | 广告 ID | | `$PresetAdPlatform` | `default_user` | N | string\[] | 媒体平台 | | `$PresetChannel` | `default_user` | N | string\[] | 渠道列表 | | `$PresetPromotion` | `default_user` | N | string\[] | 推广活动 | | `$PresetWxOpenId` | `default_user` | N | string\[] | openid | | `$PresetClientId` | `default_user` | N | string\[] | 客户 ID | | `$PresetUserCid` | `default_user` | N | string\[] | 创意 ID | | `$PresetUserGid` | `default_user` | N | string\[] | 计划 ID | | `$PresetAppVersion` | `default_user` | N | string\[] | 注册版本 | | `turbo_promoted_object_id` | `user_re_attribute` | N | string\[] | 再归因-推广活动 | | `create_time` | `user_re_attribute` | N | string\[] | 再归因-时间 | | `channel` | `user_re_attribute` | N | string\[] | 再归因-渠道 | | `click_company` | `user_re_attribute` | N | string\[] | 再归因-媒体平台 | | `gid` | `user_re_attribute` | N | string\[] | 再归因-计划 ID | | `advertiser_id` | `user_re_attribute` | N | string\[] | 再归因-广告账户 ID | | `cid` | `user_re_attribute` | N | string\[] | 再归因-创意 ID | | `aid` | `user_re_attribute` | N | string\[] | 再归因-广告 ID | | `csite` | `user_re_attribute` | N | string\[] | 再归因-版位 | | `RetargetingCount` | `user_re_attribute` | N | int\[] | 累计再归因次数 | ### global\_conditions 示例 [#global_conditions-示例] **示例 1**：查询注册时间在 2026-07-01 至 2026-07-02 之间的用户数据。 ```json [ { "operator": "RANGE_IN", "field": "$UserCreateTime", "type": "default_user", "value": [ "2026-07-01 00:00:00", "2026-07-02 23:59:59" ] } ] ``` **示例 2**：查询再归因时间在 2026-07-01 至 2026-07-02 之间的用户数据。 ```json [ { "operator": "RANGE_IN", "field": "create_time", "type": "user_re_attribute", "value": [ "2026-07-01 00:00:00", "2026-07-02 23:59:59" ] } ] ``` *** ## GroupByObject [#groupbyobject] 分组维度对象，用于对结果按指定字段进行分组。 | 字段 | 必填 | 参数类型 | 描述 | | ---------- | -- | ------ | ------------------------------------------------------- | | `field` | Y | string | 分组字段名。同 [GlobalConditionObject](#globalconditionobject) | | `type` | Y | string | 字段类型。同 [GlobalConditionObject](#globalconditionobject) | | `group_by` | N | string | 分组方式，与 `field` 相同 | *** ## AggregateConfigObject [#aggregateconfigobject] 聚合配置对象，用于控制数据聚合计算方式。 | 字段 | 必填 | 参数类型 | 描述 | | ------------------------ | -- | ---------------- | ------------------------------------------------- | | `to_calc_type` | N | string | 计算类型，`approximate`（近似计算，速度更快）或 `precise`（精确计算） | | `period_calc_method_map` | N | PeriodCalcObject | 阶段汇总配置。具体参见 [PeriodCalcObject](#periodcalcobject) | *** ## PeriodCalcObject [#periodcalcobject] 附加配置对象。 | 字段 | 必填 | 参数类型 | 描述 | | -------------------- | -- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_index` | N | int | 指标下标值从 0 开始（`query_item_list` 下标或者 `custom_query_item_list` 下标） | | `period_calc_method` | N | string | 快速加和时（`approximate`），`period_calc_method` 支持五种传参：`sum`、`average`、`average_int`、`max`、`min`。精准合计时（`precise`），`period_calc_method` 支持两种传参：`weighted_avg`（只能用于除法）、`sum`（用于加减乘） | ## ExtraDataObject [#extradataobject] 附加配置对象。 | 字段 | 必填 | 参数类型 | 描述 | | -------------------- | -- | ------ | ---------------------------------------- | | `client_server_time` | N | string | 时间基准，`CLIENT`（客户端时间，默认）或 `SERVER`（服务端时间） | *** ## 请求示例 [#请求示例] ```bash curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/events/list/' \ -H 'Content-Type: application/json' \ -H 'Authorization: YOUR_AUTH_TOKEN' \ -d '{ "event_date_list": [ "2026-06-25 00:00:00", "2026-07-01 23:59:59" ], "time_scale": "day", "extra_data": { "client_server_time": "CLIENT" }, "aggregate_config": { "to_calc_type": "approximate" }, "global_conditions": [ { "operator": "RANGE_IN", "field": "$UserCreateTime", "type": "default_user", "value": [ "2026-07-03 00:00:00", "2026-07-03 23:59:59" ] } ], "query_item_list": [ { "event_name": "$UserWithdraw", "event_label": "用户提现", "custom_name": "用户提现.总次数", "target": { "name": "PresetAllCount", "field": "PresetAllCount" }, "conditions": [], "cond_logic": "AND", "event_index": 0 } ], "app_id": 20283794, "sign": "1d0db2bb142d248ff1cf78f348c903ed" }' ``` *** ## 应答示例 [#应答示例] ### 应答参数说明 [#应答参数说明] | 字段 | 类型 | 描述 | | ------------------------- | --------- | --------------------------------------------------- | | `code` | number | 状态码，0 表示成功 | | `msg` | string | 状态描述 | | `extra` | object | 附加信息，包含 `error` 描述和 `request_id` | | `data.list` | array | 查询结果列表，外层数组对应每个查询时间段，内层数组对应每个 `query_item` | | `data.list[].start_date` | string | 查询时间段开始日期 | | `data.list[].end_date` | string | 查询时间段结束日期 | | `data.list[].target` | string | 指标名称，与 `query_item_list` 中的 `custom_name` 对应 | | `data.list[].list` | object\[] | 按时间颗粒度聚合的数据，`key` 为日期，`value` 为对应指标值；`阶段总和` 为区间内汇总值 | | `data.list[].event_index` | number | 事件序号，与 `query_item_list` 中的 `event_index` 对应 | | `data.default_limit` | number | 默认数据条数上限 | | `data.date_list` | object\[] | 查询时间段及展开的日期列表，具体参见 [date\_list 说明](#date-list-说明) | | `data.target_list` | string\[] | 本次查询涉及的所有指标名称列表 | ### date\_list 说明 [#date_list-说明] | 字段 | 类型 | 描述 | | ------------ | --------- | ----------------------- | | `start_date` | string | 时间段开始日期，格式 `YYYY-MM-DD` | | `end_date` | string | 时间段结束日期，格式 `YYYY-MM-DD` | | `date_list` | string\[] | 按 `time_scale` 展开的日期列表 | ### 应答 JSON 示例 [#应答-json-示例] ```json { "data": { "list": [ [ { "start_date": "2026-06-25", "end_date": "2026-07-01", "target": "用户提现.总次数", "list": [ { "阶段总和": 0, "2026-06-25": 0, "2026-06-26": 0, "2026-06-27": 0, "2026-06-28": 0, "2026-06-29": 0, "2026-06-30": 0, "2026-07-01": 0 } ], "event_index": 0 } ] ], "default_limit": 5000, "date_list": [ { "start_date": "2026-06-25", "end_date": "2026-07-01", "date_list": [ "2026-06-25", "2026-06-26", "2026-06-27", "2026-06-28", "2026-06-29", "2026-06-30", "2026-07-01" ] } ], "target_list": [ "用户提现.总次数" ] }, "extra": { "error": "", "request_id": "756dc1ae7b6640b08314b06f3c81b98a" }, "code": 0, "msg": "成功" } ```