申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

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

请求方法

POST

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

body 请求参数

字段	必填	参数类型	描述
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"]
metrics_list	Y	string[]	预置的指标字段数组，通过【报表指标查询接口】可查询到的所有可用指标列表。
custom_metrics_list	N	string[]	自定义指标字段数组，通过【报表指标查询接口】可查询到的所有可用指标列表。
filters	Y	FilterObject[]	数据筛选条件数组，具体参见【FilterObject】必填筛选项：appid(引力应用ID)/project_id(项目ID)
data_conf	N	DataConfigObject	数据配置对象，具体参见【DataConfigObject】
sign	Y	string	签名，详情请参考【签名生成】

FilterObject 筛选条件对象

字段	必填	参数类型	描述	必填筛选项
field	Y	string	要筛选的字段名，具体参见【筛选条件字段参考表(field) 】	appid(引力应用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

请求示例

curl --location --request POST 'https://api-insight.gravity-engine.com/openapi/api/v1/report/adreport/custom_get/' \
--header 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTNhNGQifQ.69aOJT6ye57HZOWpXMmunAhkZ7bY1fOzKY6zdGdQDfs' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: api-insight.gravity-engine.com' \
--header 'Connection: keep-alive' \
--data-raw '{
    "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"
    ],
   "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": "成功"
}

其他信息

分组规则

引力支持同时根据多个维度来聚合查询数据：

但是需要遵循以下互斥规则，标 ❌ 的两个维度不可以同时查询，否则会报错或者数据不准确：

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

报表查询