服务端集成 · 报表查询 · 多维报表

说明如何通过 Gravity Engine OpenAPI 查询媒体消耗、后向回收等多维广告报表数据，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力后台广告报表页数据，包括媒体消耗、产品后向回收等数据指标。

数据更新频率

数据每 15~30 分钟更新一次。
一般行为发生口径的历史数据不会变化，除数据有问题需要校对时会更新历史数据。
曝光归因口径的数据会随着用户行为的发生而不断变化。

申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

https://api-insight.gravity-engine.com/openapi/api/v1/report/adreport/custom_get/

请求方法

POST

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

body 请求参数

当 data_dims 参数中传入了 bundle_id 或 channel 维度时，metrics_list 中必须至少包含一个非平台指标。

平台指标：名称以平台_ 或媒体名称开头的指标，例如 ap_cost（平台_消耗）、bytedance_install_finish_rate（巨量_安卓安装完成率）。

非平台指标：名称不以平台_ 或媒体名称开头的指标，例如 standard_register_cnt（标准_注册数）。

字段	必填	参数类型	描述
`time_dims`	Y	string	时间维度聚合粒度，可选值：`total`（汇总）、`month`（按月）、`week`（按周）、`day`（按天）、`hour`（按小时）
`data_dims`	N	string[]	数据维度字段数组，用于数据分组，具体参见【数据维度字段参考表 (data_dims)】
`relate_dims`	N	object	关联维度映射对象，`key` 为主维度字段，`value` 为需要关联查询的字段列表，具体参见【关联维度字段参考表(relate_dims)】
`date_list`	Y	string[]	查询日期范围，格式：["开始日期", "结束日期"]，如：["2025-05-05", "2025-05-12"]。区间范围不超过 180 天
`metrics_list`	Y	string[]	预置的指标字段数组，通过【报表指标查询接口】可查询到的所有可用指标列表。
`custom_metrics_list`	N	string[]	自定义指标字段数组，通过【报表指标查询接口】可查询到的所有可用指标列表。
`filters`	Y	FilterObject[]	数据筛选条件数组，具体参见 FilterObject。必填筛选项：`appid`（引力应用 ID，不是开发者应用 ID！）/ `project_id`（项目 ID）
`data_conf`	N	DataConfigObject	数据配置对象，具体参见 DataConfigObject
`sign`	Y	string	签名，详情请参考【签名生成】

FilterObject 筛选条件对象

字段	必填	参数类型	描述	必填筛选项
`field`	Y	string	要筛选的字段名，具体参见【筛选条件字段参考表(field)】	`appid`（引力应用 ID，不是开发者应用 ID！）/ `project_id`（项目 ID）
`operator`	Y	string	筛选操作符，具体参见【操作符说明(operator)】
`values`	Y	any[]	筛选值数组，根据操作符类型传入对应值

DataConfigObject 数据配置对象

字段	必填	参数类型	描述
`decimal_point`	N	number	数值精度（小数点位数），默认值：4
`minigame_pay_shared_ratio`	N	number	小游戏支付分成比例，默认值：100
`multi_keys`	N	array[int]	多日指标的关键日期枚举，最大数不超过 365。默认为 1-7 日
`asa_time_zone`	N	string	默认 UTC，可传入 `Asia/Shanghai`
`minigame_pay_shared_ratio`	N	int	小游戏的安卓分成比例：分成比例应该大于 0 小于等于 100。默认为 100
`minigame_pay_shared_ratio_ios`	N	int	小游戏的 iOS 分成比例：分成比例应该大于 0 小于等于 100。默认为 100

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/adreport/custom_get/' \
-H 'Content-Type: application/json' \
-H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTNhNGQifQ.69aOJT6ye57HZOWpXMmunAhkZ7bY1fOzKY6zdGdQDfs' \
-d '{
    "sign": "c0e222d1df21ca9f055c1b1ad0f8c510",
    "filters": [
        {
            "field": "click_company",
            "operator": "IN",
            "values": [
                "asa"
            ]
        },
        {
            "field": "app_id",
            "operator": "EQUALS",
            "values": [
                21295084
            ]
        }
    ],
    "time_dims": "day",
    "data_dims": [
        "advertiser_id",
        "gid",
        "aid",
        "turbo_promoted_object_id"
    ],
    "relate_dims": {
        "turbo_promoted_object_id": [
            "turbo_promoted_object_name"
        ]
    },
    "metrics_list": [
        "ap_cost",
        "ap_show",
        "ap_click",
        "ap_activate"
    ],
    "date_list": [
        "2025-10-21",
        "2025-10-21"
    ]
}'

应答示例

{
    "data": {
        "data_dims": [
            "stat_time",
            "advertiser_id",
            "gid",
            "aid",
            "click_company"
        ],
        "time_dims": "day",
        "page_info": {
            "total": 0
        },
        "list": [],
        "total": {},
        "extra_data": {},
        "tips": ""
    },
    "extra": {
        "error": "",
        "request_id": "95dcff99373b4a8c8d8a0231e039583e"
    },
    "code": 0,
    "msg": "成功"
}

其他信息

分组规则

引力支持同时根据多个维度来聚合查询数据，但需遵循以下互斥规则，标 ❌ 的两个维度不可以同时查询，否则会报错或者数据不准确：

字段	日期	媒体	账户	计划	广告	创意	渠道	设备类型	优化师	推广活动	版位	部门
日期	-	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
媒体	✅	-	✅	✅	✅	✅	✅	❌	✅	✅	✅	✅
账户	✅	✅	-	✅	✅	✅	✅	✅	✅	✅	❌	✅
计划	✅	✅	✅	-	✅	✅	✅	✅	✅	✅	❌	✅
广告	✅	✅	✅	✅	-	✅	✅	✅	✅	✅	❌	✅
创意	✅	✅	✅	✅	✅	-	✅	✅	✅	✅	❌	✅
渠道	✅	✅	✅	✅	✅	✅	-	✅	❌	❌	❌	❌
设备类型	✅	❌	✅	✅	✅	✅	✅	-	✅	✅	❌	✅
优化师	✅	✅	✅	✅	✅	✅	❌	✅	-	✅	❌	✅
推广活动	✅	✅	✅	✅	✅	✅	❌	✅	✅	-	❌	❌
版位	✅	✅	❌	❌	❌	❌	❌	❌	❌	❌	-	❌
部门	✅	✅	✅	✅	✅	✅	❌	✅	✅	❌	❌	-

多维报表