服务端集成 · 报表查询 · 素材数据报表

说明如何通过 Gravity Engine OpenAPI 查询素材维度的消耗、曝光、点击与转化数据，涵盖认证、请求参数、筛选条件和返回字段。

此接口用于获取引力后台素材报表页数据，包括素材展点消数据、产品后向回收等数据指标。

数据更新频率

素材报表的后向数据为 T+1 更新一次。
媒体消耗数据每隔 1 小时更新一次。

申请引力开发者应用

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

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

接口限频

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

接口信息

请求地址

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

请求方法

POST

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

body 请求参数

字段	必填	参数类型	描述
`data_dims`	Y	string[]	数据维度列表，单选数组，可选枚举值：`material`（素材）、`album_id`（专辑）、`designer_id`（设计师）、`creative_user_id`（创意人）。举例：["material"] 表示按素材维度
`time_line`	N	string	固定值：`bytedance_std`。传入此参数以指定数据来源为巨量智擎
`relate_dims`	N	string[]	关联维度。枚举值：`app_id`（产品）、`advertiser_id`（账户）、`company`（账户主体）、`operator_id`（优化师）、`site_set`（广告版位）、`tag_list`（素材标签）
`date_dims`	Y	string	日期维度，字符串，可选枚举值：`day`（分日）、`week`（分周）、`month`（分月）、`total`（汇总）。举例：`day` 表示按日拆分
`date_list`	Y	string[]	起始日期数组，格式 YYYY-MM-DD，举例：["2023-08-14", "2023-08-19"]
`metrics_list`	Y	string[]	指定需要的素材指标名称，不同媒体情况下，参考的指标不一样，分别如下：不限、巨量引擎、腾讯广告、磁力引擎
`gravity_metrics_list`	Y	string[]	指定需要的引力后向指标名称，参考这个文件
`filters`	Y	FilterObject	具体参见 FilterObject
`page`	Y	number	当前页
`page_size`	Y	number	当前页大小
`sign`	Y	string	签名，详情请参考【签名生成】

FilterObject

必填筛选项：ad_platform，values 取值：

aggregate（不限）
kuaishou（快手）
bytedance（字节）
tencent（腾讯）

[
  {
    "field": "ad_platform",
    "operator": "EQUALS",
    "values": ["aggregate"]
  }
]

请求示例

curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/material_get/' \
-H 'Content-Type: application/json' \
-H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiMWMyOGU2MDNlNzE2NGNiYWFjZWEwMGU5ODkxNTKKKQifQ.mxgK7EqBjCFDThH5nmQco9kOXf8LcbSjonScrVt1GsA' \
-d '{
    "date_dims": "day",
    "data_dims": ["material"],
    "date_list": ["2025-02-01", "2025-02-07"],
    "metrics_list": ["AdCost"],
    "gravity_metrics_list": [],
    "filters": [
        {
            "field": "ad_platform",
            "operator": "EQUALS",
            "values": ["aggregate"]
        }
    ],
    "page": 1,
    "page_size": 10,
    "relate_dims": ["app_id", "advertiser_id", "company", "operator_id", "site_set", "tag_list"],
    "sign": "0683929ce5d85bb32592e9bbbba8b20"
}'

应答示例

应答参数指标说明

请参考：素材数据报表应答字段说明

主要关注 list、page_info 和 total，具体示例如下：

{
  "data": {
    "list": [
      {
        "file_md5": "1fbf9bb1f352e6ca167ea1565fd37016",
        "gravity_material_id": "6411380209881088",
        "AdCost": 0.52,
        "AdShow": 301,
        "AdAvgShowCost": 1.7276,
        "AdClick": 10,
        "AdClickRate": 0.0332,
        "AdAvgClickCost": 0.052,
        "AdConvert": 0,
        "AdConvertCost": 0,
        "AdConvertRate": 0,
        "AdDeepConvert": 0,
        "AdDeepConvertCost": 0,
        "AdDeepConvertRate": 0,
        "AdAppActivate": 0,
        "AdAppActivateRate": 0,
        "AdAppActivateCost": 0,
        "AdAppRegister": 0,
        "AdAppRegisterRate": 0,
        "AdAppRegisterCost": 0,
        "AdAppFirstPay": 0,
        "AdAppFirstPayRate": 0,
        "AdAppFirstPayCost": 0,
        "AdAppFirstDayPay": 0,
        "AdAppFirstDayPayAmount": 0,
        "AdAppGamePay": 0,
        "AdAppGamePayCost": 0,
        "AdAppGamePayAmount": 0,
        "AdAppKeyActive": 0,
        "AdAppKeyActiveRate": 0,
        "AdAppKeyActiveCost": 0,
        "AdAppRetention": 0,
        "AdAppRetentionRate": 0,
        "AdAppRetentionCost": 0,
        "AppMultiDayGamePayAmountBuried_6": 0,
        "file_type": "video",
        "folder_id": 131297,
        "file_name": "上传测试16",
        "thumbnail_url": "https://gravity-client-resource.oss-cn-hangzhou.aliyuncs.com/1/video/1fbf9bb1f352e6ca167ea1565fd37016.mp4?spm=a2c4g.11186623.2.1.yjOb8V&x-oss-process=video/snapshot,t_7000,f_jpg,w_1080,h_1920,m_fast",
        "file_url": "https://gravity-client-resource.oss-cn-hangzhou.aliyuncs.com/1/video/1fbf9bb1f352e6ca167ea1565fd37016.mp4",
        "folder_name": "文件夹推送"
      }
    ],
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 4,
      "total_page": 1
    },
    "total": {
      "AdCost": 4.75,
      "AdShow": 394,
      "AdAvgShowCost": 12.0558,
      "AdClick": 26,
      "AdClickRate": 0.066,
      "AdAvgClickCost": 0.1827,
      "AdConvert": 0,
      "AdConvertCost": 0,
      "AdConvertRate": 0,
      "AdDeepConvert": 0,
      "AdDeepConvertCost": 0,
      "AdDeepConvertRate": 0,
      "AdAppActivate": 0,
      "AdAppActivateRate": 0,
      "AdAppActivateCost": 0,
      "AdAppRegister": 0,
      "AdAppRegisterRate": 0,
      "AdAppRegisterCost": 0,
      "AdAppFirstPay": 0,
      "AdAppFirstPayRate": 0,
      "AdAppFirstPayCost": 0,
      "AdAppFirstDayPay": 0,
      "AdAppFirstDayPayAmount": 0,
      "AdAppGamePay": 0,
      "AdAppGamePayCost": 0,
      "AdAppGamePayAmount": 0,
      "AdAppKeyActive": 0,
      "AdAppKeyActiveRate": 0,
      "AdAppKeyActiveCost": 0,
      "AdAppRetention": 0,
      "AdAppRetentionRate": 0,
      "AdAppRetentionCost": 0,
      "AppMultiDayGamePayAmountBuried_6": 0
    },
    "update_at": {
      "tencent": "",
      "kuaishou": "",
      "bytedance": ""
    }
  },
  "extra": {
    "error": ""
  },
  "code": 0,
  "msg": "成功"
}

素材数据报表