# 多维报表

> 来源：https://help.gravity-engine.com/docs/server-integration/reporting/multidimensional-reports
> 说明如何通过 Gravity Engine OpenAPI 查询媒体消耗、后向回收等多维广告报表数据，涵盖认证、请求参数、筛选条件和返回字段。



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

## 数据更新频率 [#数据更新频率]

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

## 申请引力开发者应用 [#申请引力开发者应用]

在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，申请之后，我们将在一个工作日内完成审核，审核通过之后，您的开发者应用才可以正常拉取数据。

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

## 接口限频 [#接口限频]

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

## 接口信息 [#接口信息]

### 请求地址 [#请求地址]

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

### 请求方法 [#请求方法]

POST

### Header [#header]

| 字段            | 类型     | 描述                                                            |
| ------------- | ------ | ------------------------------------------------------------- |
| Authorization | string | 具体如何生成，请参考 [【签名生成】](/docs/server-integration/request-signing) |

### body 请求参数 [#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)】](/docs/appendix/multidimensional-report-fields)                             |
| `relate_dims`         | N  | object           | 关联维度映射对象，`key` 为主维度字段，`value` 为需要关联查询的字段列表，具体参见 [【关联维度字段参考表(relate\_dims)】](/docs/appendix/multidimensional-report-fields) |
| `date_list`           | Y  | string\[]        | 查询日期范围，格式：\["开始日期", "结束日期"]，如：\["2025-05-05", "2025-05-12"]。区间范围不超过 180 天                                                  |
| `metrics_list`        | Y  | string\[]        | 预置的指标字段数组，通过 [【报表指标查询接口】](/docs/server-integration/reporting/report-metrics) 可查询到的所有可用指标列表。                                |
| `custom_metrics_list` | N  | string\[]        | 自定义指标字段数组，通过 [【报表指标查询接口】](/docs/server-integration/reporting/report-metrics) 可查询到的所有可用指标列表。                                |
| `filters`             | Y  | FilterObject\[]  | 数据筛选条件数组，具体参见 [FilterObject](#filterobject-筛选条件对象)。必填筛选项：`appid`（引力应用 ID，不是开发者应用 ID！）/ `project_id`（项目 ID）                 |
| `data_conf`           | N  | DataConfigObject | 数据配置对象，具体参见 [DataConfigObject](#dataconfigobject-数据配置对象)                                                                   |
| `sign`                | Y  | string           | 签名，详情请参考 [【签名生成】](/docs/server-integration/request-signing)                                                                |

### FilterObject 筛选条件对象 [#filterobject-筛选条件对象]

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

### DataConfigObject 数据配置对象 [#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 |

## 请求示例 [#请求示例]

```bash
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"
    ]
}'
```

## 应答示例 [#应答示例]

```json
{
    "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": "成功"
}
```

## 其他信息 [#其他信息]

### 分组规则 [#分组规则]

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

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