服务端集成 · 报表查询 · 事件分析报表

说明如何通过 Gravity Engine OpenAPI 查询事件分析结果及其时间粒度、指标和筛选条件，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力收集到的用户事件分析数据，支持按时间颗粒度聚合、多维度分组及自定义查询指标。

数据更新频率： 数据分钟级更新延迟，高峰期时间可能会变长，极端情况可能会延迟 10 分钟以上。

申请引力开发者应用

在正式接入本接口之前，您需要在引力后台-引力开发者页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。

创建好开发者应用之后，请复制 app_key 参数，并发送给研发同学以供后续接口调用使用。

接口限频

默认接口限频：每 10 秒 10 次。接口限频按开发者应用维度统计，即同一个 app_key 下的应用共用同一套频次限制。如果开发者绑定应用过多导致频繁触发限频，请联系引力运营评估后提升限频等级。

接口信息

请求地址

https://api-insight.gravity-engine.com/openapi/api/v1/report/events/list/

请求方法

POST

字段	类型	描述
Authorization	string	具体如何生成，请参考【签名生成】

Body 请求参数

字段	必填	参数类型	描述
`app_id`	Y	number	查询的应用引力 ID，可以在引力后台-应用管理页面获取
`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 枚举
`query_item_list`	Y	QueryItemObject[]	查询指标列表。具体参见 QueryItemObject
`custom_query_item_list`	N	CustomQueryObject[]	自定义公式查询列表。具体参见 CustomQueryObject
`global_conditions`	N	GlobalConditionObject[]	全局过滤条件数组。具体参见 GlobalConditionObject
`global_cond_logic`	N	string	全局过滤条件逻辑。`AND`（默认）或 `OR`
`group_by_list`	N	GroupByObject[]	分组维度列表。具体参见 GroupByObject
`aggregate_config`	N	AggregateConfigObject	聚合配置。具体参见 AggregateConfigObject
`extra_data`	N	ExtraDataObject	附加配置。具体参见 ExtraDataObject
`sign`	Y	string	签名。详情请参考【签名生成】

time_scale 枚举

值	说明
`minute`	按分钟聚合
`hour`	按小时聚合
`day`	按天聚合
`week`	按周聚合
`month`	按月聚合
`total`	汇总（不拆分时间维度）

QueryItemObject

查询指标对象，用于描述需要统计的事件及指标。

字段	必填	参数类型	描述
`event_name`	Y	string	事件名，如 `$UserWithdraw`，具体的事件名称请参考元事件页面
`event_label`	N	string	事件显示名称，如 `用户提现`
`custom_name`	N	string	自定义指标名称，如 `用户提现.总次数`
`target`	Y	TargetObject	统计目标，具体参见 TargetObject
`conditions`	Y	object[]	事件过滤条件列表。同 GlobalConditionObject
`cond_logic`	N	string	事件过滤条件逻辑，`AND`（默认）或 `OR`
`event_index`	N	number	事件序号，从 0 开始，用于标识响应中对应的事件

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 示例

[
  {
    "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

字段	必填	参数类型	描述
`custom_name`	Y	string	自定义公式名称。
`formula`	Y	string	公式。如 `x/x`（x 代表指标，即「指标/指标」）、`x/100`（指标除以常量），其他同理
`query_item_list`	Y	QueryItemObject[]	同 QueryItemObject
`decimal_point`	N	string	保留小数。默认 `two_point`（两位小数）、`three_point`（3 位小数）、`four_point`（4 位小数）
`event_index`	Y	int	指标返回序列 ID

GlobalConditionObject

全局过滤条件对象，用于对用户属性或事件属性进行筛选。

字段	必填	参数类型	描述
`field`	Y	string	过滤字段名。用户默认属性/再归因属性支持的过滤字段见下表；事件属性的具体字段参见元事件页面的事件属性；用户属性的具体字段参见元数据-用户属性
`type`	Y	string	字段类型，例如 `default_user`（用户默认属性）、`user`（用户属性）、`user_re_attribute`（用户再归因属性）、`event`（事件属性）
`operator`	Y	string	查询操作符，支持的操作符参见【操作符说明】
`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 示例

示例 1：查询注册时间在 2026-07-01 至 2026-07-02 之间的用户数据。

[
  {
    "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 之间的用户数据。

[
  {
    "operator": "RANGE_IN",
    "field": "create_time",
    "type": "user_re_attribute",
    "value": [
      "2026-07-01 00:00:00",
      "2026-07-02 23:59:59"
    ]
  }
]

GroupByObject

分组维度对象，用于对结果按指定字段进行分组。

字段	必填	参数类型	描述
`field`	Y	string	分组字段名。同 GlobalConditionObject
`type`	Y	string	字段类型。同 GlobalConditionObject
`group_by`	N	string	分组方式，与 `field` 相同

AggregateConfigObject

聚合配置对象，用于控制数据聚合计算方式。

字段	必填	参数类型	描述
`to_calc_type`	N	string	计算类型，`approximate`（近似计算，速度更快）或 `precise`（精确计算）
`period_calc_method_map`	N	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