服务端集成 · 报表查询 · 变现细查报表

说明如何通过 Gravity Engine OpenAPI 查询用户广告事件及广告变现明细数据，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力收集到的用户广告事件数据。

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

申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

https://api-insight.gravity-engine.com/openapi/api/v1/report/monetization_detail/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"]`（时间区间范围最大 90 天）
`global_conditions`	N	GlobalConditionObject[]	用户属性筛选，具体参见 GlobalConditionObject
`local_conditions`	N	LocalConditionObject[]	事件属性筛选，具体参见 LocalConditionObject
`page`	N	number	查询的页码，从 1 开始
`page_size`	N	number	单页的大小，最大支持 500
`sign`	Y	string	签名，详情请参考【签名生成】

GlobalConditionObject

全局过滤条件对象，用于对用户的属性筛选。

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

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

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

示例 1：查询注册时间在 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"
    ]
  }
]

示例 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"
    ]
  }
]

LocalConditionObject

用于对事件属性进行筛选。

字段	必填	参数类型	描述
`field`	Y	string	过滤字段名，格式：`event` + 事件属性。支持的字段参见元事件页面 `$AdShow` 事件的事件属性
`type`	Y	string	字段类型：`event`（事件属性）
`operator`	Y	string	查询操作符，支持的操作符参见【操作符说明】
`value`	Y	string[]	过滤值数组

local_conditions 示例

示例：筛选事件属性 ecpm 等于 123 的事件数据（field 格式为 event + 事件属性）。

[
  {
    "field": "event$ecpm",
    "type": "event",
    "operator": "EQUALS",
    "value": ["123"]
  }
]

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/monetization_detail/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"
    ],
    "global_conditions": [
        {
            "operator": "RANGE_IN",
            "field": "create_date_list",
            "type": "default_user",
            "value": [
                "2026-07-01 00:00:00",
                "2026-07-02 23:59:59"
            ]
        }
    ],
    "page": 1,
    "app_id": 20283794,
    "page_size": 1,
    "sign": "a2b27da239d729b39ae5f047d2c67704"
}'

应答示例

应答参数说明

字段	类型	描述
`code`	number	状态码，0 表示成功
`msg`	string	状态描述
`extra`	object	附加信息，包含 `error` 描述和 `request_id`
`data.page_info`	object	分页信息
`data.page_info.page`	number	当前页码
`data.page_info.page_size`	number	每页数量
`data.page_info.total_number`	number	总记录数
`data.page_info.total_page`	number	总页数
`data.list`	object[]	数据列表，具体字段参见【变现细查报表指标说明】
`data.total`	object[]	汇总数据

{
  "data": {
    "page_info": {
      "page": 1,
      "page_size": 1,
      "total_number": 4204,
      "total_page": 4204
    },
    "list": [
      {
        "CreateTime": "2026-07-01 14:23:17",
        "AdClickTime": null,
        "ClientID": "r4hp0uxvzj6vfw0r",
        "user_id": 10811009030,
        "modify_time": "2026-07-01 09:12:19",
        "AdPlatform": "baidu",
        "Channel": "base_channel",
        "Version": 0,
        "TurboPromotedObjectID": "default_20283794",
        "Name": "default",
        "WXOpenID": "",
        "AdvertiserID": "",
        "AdAid": "",
        "AdGid": "",
        "AdCid": "",
        "CSite": "",
        "LatestLoginDay": "20260701",
        "user$ad_24h_avg_ecpm": 1188.08,
        "user$ad_24h_count": 13,
        "user$ad_24h_ltv": 15445.0,
        "user$ad_avg_ecpm": 1457.71,
        "user$ad_count": 276,
        "user$ad_ltv": 402327.0,
        "user$ad_max_ecpm": 2998.0,
        "user$os": "ios",
        "user$pay_amount_sum": 8764300,
        "user$pay_count": 367,
        "user$pay_max_amount": 199800,
        "user$first_pay_method": "支付宝",
        "user$first_pay_reason": "属性加成道具",
        "user$first_pay_time": "2026-07-01 23:28:51",
        "user$province": "吉林省",
        "user$city": "白山市",
        "user$country": "中国",
        "AdEventTime": "2026-07-01 23:59:59",
        "samount": 177.0,
        "event$ad_type": "reward",
        "event$adn_type": "wechat",
        "event$ecpm": 177.0,
        "event$scene": "1005",
        "event$today_first_scene": "1005",
        "event$trace_id": "96afd83109004a959a219c19838c534d",
        "event$os": "ios",
        "event$ip": "230.161.112.56",
        "event$browser": "Python aiohttp",
        "event$browser_version": "3.10.10",
        "event$province": "吉林省",
        "event$city": "白山市",
        "event$country": "中国"
      }
    ],
    "total": []
  },
  "extra": {
    "error": "",
    "request_id": "fc2496ab0b584dc1ba4ec7f40a64cfd8"
  },
  "code": 0,
  "msg": "成功"
}

变现细查报表