服务端集成 · 报表查询 · 用户信息报表

说明如何通过 Gravity Engine OpenAPI 查询用户归因、基础信息与用户属性数据，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力收集到的用户信息数据，包括用户的归因信息、基础信息、属性信息。

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

申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

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

请求方法

POST

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

body 请求参数

字段	必填	参数类型	描述
`app_id`	Y	number	查询的应用引力 ID，可以在引力后台-应用管理页面获取
`user_filtering`	Y	UserFilterObject	用户默认属性过滤，具体参见 UserFilterObject
`event_filtering`	N	EventFilterObject	回传筛选过滤，具体参见 EventFilterObject
`property_condition`	N	PropertyConditionObject	再归因筛选，具体参见 PropertyConditionObject
`order_by_list`	N	OrderByObject	排序数组，具体参见 OrderByObject
`page`	N	number	查询的页码，从 1 开始（page 最大为 5000）
`page_size`	N	number	单页的大小，最大支持 2000
`sign`	Y	string	签名，详情请参考【签名生成】

UserFilterObject

用户默认属性过滤

字段	必填	参数类型	描述
`create_date_list`	Y	string[]	用户注册时间，如 ["2023-03-01", "2023-03-10"]（时间区间范围最大 120 天）
`ad_platform_list`	N	string[]	广告平台枚举值，具体详见广告平台枚举
`channel_list`	N	string[]	渠道列表，例如 `['xiaomi', 'huawei']`
`version_list`	N	number[]	版本列表，例如 `[123, 125]`
`turbo_promoted_object_id_list`	N	string[]	引力推广活动 ID 列表
`advertiser_id_list`	N	string[]	广告账户 ID 列表
`gid_list`	N	string[]	计划 ID 列表
`aid_list`	N	string[]	广告 ID 列表
`cid_list`	N	string[]	创意 ID 列表
`wx_openid_list`	N	string[]	openid 列表
`client_id_list`	N	string[]	用户 clientID 列表

EventFilterObject

回传筛选过滤

字段	支持查询类型	参数格式	描述
`postback_filtering`	单选查询	PostBackItem[]	具体见 PostBackItem

PostBackItem

PostBackItem 为一个查询单元，其中包含两个字段：

字段	类型	描述
`event_type`	string	查询事件，事件枚举值如下表
`status`	string	回传状态，`0` 为未回传，`1` 为回传成功，`2` 为回传失败，`3` 为回传跳过

event_filtering 举例如下：

查询首次付费事件状态为回传跳过的用户

{
  "event_filtering": {
    "postback_filtering": [
      {
        "event_type": "first_pay",
        "status": "3"
      }
    ]
  }
}

event_type 事件枚举值如下：

事件枚举值	事件名称
`activate`	激活
`register`	注册
`pay`	付费
`twice`	次留
`key_active`	关键行为
`withdraw_iaa`	短期退订
`create_role`	创角
`login`	登录
`customer_effective`	有效获客
`wx_launch`	微信小程序调起
`re_active`	关键页面浏览
`retention_2d`	2 日留存
`retention_3d`	3 日留存
`retention_4d`	4 日留存
`retention_5d`	5 日留存
`retention_6d`	6 日留存
`retention_7d`	7 日留存
`retention_14d`	14 日留存
`retention_30d`	30 日留存
`service_pay_success`	服务购买成功
`complete_order`	订单提交（非付费）
`first_day_pay`	首日付费
`first_pay`	首次付费
`ad_quality`	广告变现
`game_action`	游戏行为
`action_valid`	有效行为

PropertyConditionObject

property_condition 用于按再归因属性筛选用户，其中 field 为再归因字段（例如 create_time 表示筛选再归因时间），type 为 user_re_attribute（用户再归因属性），operator 为查询操作符，value 为过滤值数组。举例如下：

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

OrderByObject

如果想在查询时排序，需要传入 order_by_list 参数，其中 order_by_list 为一个数组，数组中的元素为 OrderByObject 类型，OrderByObject 中包含两个字段：

field：排序字段，支持的排序字段参考【排序指标】
sort：排序方式，支持的排序方式有：0（升序）和 1（降序）

order_by_list 具有顺序，会优先按照第一个排序字段进行排序，如果第一个排序字段相同，则按照第二个排序字段进行排序，以此类推。

order_by_list 举例如下：

优先按照付费次数降序，其次按照付费金额升序排序

[
  {
    "field": "user$pay_count",
    "sort": 1
  },
  {
    "field": "user$pay_amount_sum",
    "sort": 0
  }
]

排序指标

目前支持排序的字段如下，其中字符串按照字符串字母排序，数字按照数字大小排序，时间类型按照时间先后排序：

字段	含义
`ClientID`	client ID
`AdPlatform`	媒体平台
`Channel`	渠道
`Version`	客户端版本
`TurboPromotedObjectID`	推广活动 ID
`WXOpenID`	openid
`AdvertiserID`	广告账户 ID
`AdAid`	广告 ID
`LatestLoginDay`	最近登录日期
`user$pay_amount_sum`	用户付费总额
`user$pay_count`	用户付费次数
`user$pay_max_amount`	用户付费最大金额

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/user/list/' \
-H 'Content-Type: application/json' \
-H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiYmY5YjNhZjU2ZDNkNGM5ZDkyZTFhYDYxMGQwNWQifQ.AfTDDjv4xQCI79Pyxw4pWSGIwqtwaIGOEwterZgI-q0' \
-d '{
  "app_id": 24390285,
  "user_filtering": {
    "create_date_list": [
      "2026-04-02",
      "2026-04-02"
    ]
  },
  "event_filtering": {
    "postback_filtering": [
      {
        "event_type": "activate",
        "status": "0"
      }
    ]
  },
  "sign": "4456c2f50c06811d6964eacb3abf"
}'

应答参数指标说明

请参考用户信息报表应答字段说明。

应答示例

{
  "data": {
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 32,
      "total_page": 2
    },
    "list": [
      {
        "CreateTime": "2024-07-23 09:01:40",
        "ClientID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdPlatform": "",
        "Channel": "xxx",
        "Version": 2040,
        "TurboPromotedObjectID": "default_13142548",
        "Name": "oeBZI5MHOLvm-Cf8yK9X0",
        "WXOpenID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdvertiserID": "",
        "AdAid": "",
        "AdGid": "",
        "AdCid": "",
        "CSite": "",
        "LatestLoginDay": "20240723",
        "user$ad_24h_ltv": 0,
        "user$ad_count": 0,
        "user$ad_ltv": 0,
        "user$ad_max_ecpm": 0,
        "user$brand": "HUAWEI",
        "user$channel": "xxx",
        "user$city": "宜宾市",
        "user$country": "中国",
        "user$first_pay_time": "2024-07-23 10:06:54",
        "user$first_scene": "1055",
        "user$first_visit_time": "2024-07-23 09:53:38",
        "user$gender": "",
        "user$interstitial_ad_24_ltv": 0,
        "user$interstitial_ad_count": 0,
        "user$interstitial_ad_ltv": 0,
        "user$interstitial_ad_max_ecpm": 0,
        "user$manufacturer": "HUAWEI",
        "user$model": "NOH-AN00",
        "user$name": "",
        "user$os": "android",
        "user$pay_amount_sum": 36200,
        "user$pay_count": 13,
        "user$pay_max_amount": 9800,
        "user$province": "四川省",
        "user$reward_ad_24h_ltv": 0,
        "user$reward_ad_count": 0,
        "user$reward_ad_ltv": 0,
        "user$reward_ad_max_ecpm": 0,
        "user$ta_account_id": "",
        "user$ta_distinct_id": "",
        "re_attribute_info": null,
        "device_info": {
          "DeviceId": 15291449,
          "OS": 0,
          "Idfa": "空",
          "Idfv": "BDA32D21-41DD-4098-B0C4-9DDB1F5EFFD2",
          "Caid1": "空",
          "Caid2": "空",
          "Oaid": "空",
          "Imei": "空",
          "AndroidId": "空",
          "Android_Version": "空",
          "Api_Version": 0,
          "Rom": "空",
          "Rom_version": "空",
          "Aspect_Ratio": "空",
          "Phone_Brand": "空",
          "Phone_Model": "空"
        }
      }
    ],
    "total": []
  },
  "extra": null,
  "code": 0,
  "msg": "成功"
}

用户信息报表