菜单

事件分析报表

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

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

申请引力开发者应用

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

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

接口限频

默认接口限频：每 10 s 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，区间范围不超过 120 天
time_scale	Y	string	查询时间颗粒度。具体取值参见【time_scale 枚举】
query_item_list	Y	QueryItemObject[]	查询指标列表。具体参见【QueryItemObject】
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	N	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 事件属性名字）

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
  }
]

GlobalConditionObject

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

字段	必填	参数类型	描述
field	Y	string	过滤字段名。用户默认属性/再归因属性支持字段见下表，用户属性支持字段见元数据-用户属性。事件属性格式：`event`+事件属性，具体的字段参见元事件页面事件的事件属性
type	Y	string	字段类型，例如 `default_user`（用户默认属性），`user`（用户属性），`user_re_attribute`（用户再归因属性），`event`（事件属性）
operator	Y	string	查询操作符，支持的操作符参见【操作符说明】
value	Y	string[]	过滤值数组

用户默认属性/再归因属性支持的过滤字段

字段	type	必填	参数类型	描述
create_date_list	default_user	Y	string[]	用户注册时间
modify_time_list	default_user	N	string[]	更新时间
latest_login_day_list	default_user	N	string[]	最近活跃时间
ad_click_time_list	default_user	N	string[]	广告点击时间
ad_platform_list	default_user	N	string[]	媒体平台
channel_list	default_user	N	string[]	客户端渠道
version_list	default_user	N	string[]	注册版本
turbo_promoted_object_id_list	default_user	N	string[]	推广活动
advertiser_id_list	default_user	N	string[]	账户ID
gid_list	default_user	N	string[]	计划ID
aid_list	default_user	N	string[]	广告ID
cid_list	default_user	N	string[]	创意ID
client_id_list	default_user	N	string[]	用户clientID
wx_openid_list	default_user	N	string[]	用户OpenID
csite	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 示例

//查询注册时间在 2026-07-01 至 2026-07-02 之间的用户数据：
[
  {
    "operator": "RANGE_IN",
    "field": "create_date_list",
    "type": "default_user",
    "value": [
      "2026-07-01 00:00:00",
      "2026-07-02 23:59:59"
    ]
  }
]
//查询再归因时间在 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`（精确计算）

ExtraDataObject

附加配置对象。

字段	必填	参数类型	描述
client_server_time	N	string	时间基准，`CLIENT`（客户端时间，默认）或 `SERVER`（服务端时间）

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/events/list/' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: YOUR_AUTH_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{
    "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"
  }'

应答示例

应答参数说明

字段	类型	100%描述
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 说明】
data.target_list	string[]	本次查询涉及的所有指标名称列表

date_list 说明

字段	类型	描述
start_date	string	时间段开始日期，格式 `YYYY-MM-DD`
end_date	string	时间段结束日期，格式 `YYYY-MM-DD`
date_list	string[]	按 time_scale 展开的日期列表

应答 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": "成功"
}

上一个

变现细查报表

下一个

其他

最近修改: 2026-07-06Powered by

事件分析报表

事件分析报表

申请引力开发者应用

接口限频

接口信息

请求地址

请求方法

Header

Body 请求参数

time_scale 枚举

QueryItemObject

TargetObject

预制指标

query_item_list 示例

GlobalConditionObject

用户 默认属性/再归因属性 支持的过滤字段

global_conditions 示例

GroupByObject

AggregateConfigObject

ExtraDataObject

请求示例

应答示例

应答参数说明

date_list 说明

应答 JSON 示例

用户默认属性/再归因属性支持的过滤字段