# 用户信息报表

> 来源：https://help.gravity-engine.com/docs/server-integration/reporting/user-info-reports
> 说明如何通过 Gravity Engine OpenAPI 查询用户归因、基础信息与用户属性数据，涵盖认证、请求参数、筛选条件和返回字段。



此接口用于获取引力收集到的用户信息数据，包括用户的归因信息、基础信息、属性信息。

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

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

在正式接入本接口之前，您需要在引力后台-[引力开发者](https://web.gravity-engine.com/#/manage/develop)页面申请引力开发者应用，提交后请在该页面查看审核和启用状态，审核通过并启用后，再调用本接口。

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

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

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

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

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

```text
https://api-insight.gravity-engine.com/openapi/api/v1/report/user/list/
```

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

POST

### Header [#header]

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

### body 请求参数 [#body-请求参数]

| 字段                   | 必填 | 参数类型                    | 描述                                                                               |
| -------------------- | -- | ----------------------- | -------------------------------------------------------------------------------- |
| `app_id`             | Y  | number                  | 查询的应用引力 ID，可以在引力后台-[应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面获取 |
| `user_filtering`     | Y  | UserFilterObject        | 用户默认属性过滤，具体参见 [UserFilterObject](#userfilterobject)                              |
| `event_filtering`    | N  | EventFilterObject       | 回传筛选过滤，具体参见 [EventFilterObject](#eventfilterobject)                              |
| `property_condition` | N  | PropertyConditionObject | 再归因 / 素材筛选，具体参见 [PropertyConditionObject](#propertyconditionobject)              |
| `order_by_list`      | N  | OrderByObject\[]        | 排序数组，具体参见 [OrderByObject](#orderbyobject)                                        |
| `page`               | N  | number                  | 查询的页码，从 1 开始（page 最大为 5000）                                                      |
| `page_size`          | N  | number                  | 单页的大小，最大支持 2000                                                                  |
| `sign`               | Y  | string                  | 签名，详情请参考 [【签名生成】](/docs/server-integration/request-signing)                      |

### UserFilterObject [#userfilterobject]

用户默认属性过滤

| 字段                              | 必填 | 参数类型      | 描述                                                      |
| ------------------------------- | -- | --------- | ------------------------------------------------------- |
| `create_date_list`              | Y  | string\[] | 用户注册时间，如 \["2023-03-01", "2023-03-10"]（时间区间范围最大 120 天）  |
| `ad_platform_list`              | N  | string\[] | 广告平台枚举值，具体详见 [广告平台枚举](/docs/appendix/ad-platform-enums) |
| `channel_list`                  | N  | string\[] | 渠道列表，例如 `['xiaomi', 'huawei']`                          |
| `version_list`                  | N  | number\[] | 版本列表，例如 `[123, 125]`                                    |
| `turbo_promoted_object_id_list` | N  | string\[] | 引力推广活动 ID 列表                                            |
| `advertiser_id_list`            | N  | string\[] | 广告账户 ID 列表                                              |
| `gid_list`                      | N  | string\[] | 计划 ID 列表                                                |
| `aid_list`                      | N  | string\[] | 广告 ID 列表                                                |
| `cid_list`                      | N  | string\[] | 创意 ID 列表                                                |
| `wx_openid_list`                | N  | string\[] | openid 列表                                               |
| `client_id_list`                | N  | string\[] | 用户 clientID 列表                                          |

### EventFilterObject [#eventfilterobject]

回传筛选过滤

| 字段                   | 支持查询类型 | 参数格式            | 描述                                |
| -------------------- | ------ | --------------- | --------------------------------- |
| `postback_filtering` | 单选查询   | PostBackItem\[] | 具体见 [PostBackItem](#postbackitem) |

#### PostBackItem [#postbackitem]

PostBackItem 为一个查询单元，其中包含两个字段：

| 字段           | 类型     | 描述                                          |
| ------------ | ------ | ------------------------------------------- |
| `event_type` | string | 查询事件，事件枚举值如下表                               |
| `status`     | string | 回传状态，`0` 为未回传，`1` 为回传成功，`2` 为回传失败，`3` 为回传跳过 |

`event_filtering` 举例如下：

查询首次付费事件状态为回传跳过的用户

```json
{
  "event_filtering": {
    "postback_filtering": [
      {
        "event_type": "first_pay",
        "status": "3"
      }
    ]
  }
}
```

`event_type` 事件枚举值如下：

| 事件枚举值                 | 事件名称      |
| --------------------- | --------- |
| `activate`            | 激活        |
| `register`            | 注册        |
| `pay`                 | 付费        |
| `twice`               | 次留        |
| `key_active`          | 关键行为      |
| `withdraw_iaa`        | 短期退订      |
| `create_role`         | 创角        |
| `login`               | 登录        |
| `customer_effective`  | 有效获客      |
| `wx_launch`           | 微信小程序调起   |
| `re_active`           | 关键页面浏览    |
| `retention_2d`        | 2 日留存     |
| `retention_3d`        | 3 日留存     |
| `retention_4d`        | 4 日留存     |
| `retention_5d`        | 5 日留存     |
| `retention_6d`        | 6 日留存     |
| `retention_7d`        | 7 日留存     |
| `retention_14d`       | 14 日留存    |
| `retention_30d`       | 30 日留存    |
| `service_pay_success` | 服务购买成功    |
| `complete_order`      | 订单提交（非付费） |
| `first_day_pay`       | 首日付费      |
| `first_pay`           | 首次付费      |
| `ad_quality`          | 广告变现      |
| `game_action`         | 游戏行为      |
| `action_valid`        | 有效行为      |

### PropertyConditionObject [#propertyconditionobject]

`property_condition` 用于按用户再归因属性、素材属性或素材再归因属性筛选用户，数组中的每个元素为一个查询条件。

| 字段           | 参数类型      | 描述                                                                                 |
| ------------ | --------- | ---------------------------------------------------------------------------------- |
| `field`      | string    | 查询字段，取值由 `type` 决定                                                                 |
| `type`       | string    | 字段类型，支持 `user_re_attribute`（用户再归因属性）、`material`（素材）、`material_re_attribute`（素材再归因） |
| `operator`   | string    | 查询操作符，支持 `IN`、`EQUALS`、`RANGE_IN`、`has_children`                                   |
| `value`      | string\[] | 过滤值数组；`operator` 为 `has_children` 时无需传入                                            |
| `logic`      | string    | 子条件之间的逻辑关系，`operator` 为 `has_children` 时使用，例如 `AND`                                |
| `conditions` | object\[] | 子条件数组，结构与当前条件一致，`operator` 为 `has_children` 时使用                                    |

`type` 与 `field` 的对应关系如下：

| type                    | 说明      | field 取值                                                                                                                                   |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `user_re_attribute`     | 用户再归因属性 | 再归因字段，例如 `create_time` 表示再归因时间                                                                                                             |
| `material`              | 素材属性    | 素材字段 `bytedanceMid1`–`bytedanceMid8`，含义见 [素材指标](/docs/appendix/user-info-report-metrics#material)                                          |
| `material_re_attribute` | 素材再归因属性 | 素材再归因字段 `ReAttributeBytedanceMid1`–`ReAttributeBytedanceMid8`，含义见 [素材再归因指标](/docs/appendix/user-info-report-metrics#material-re-attribute) |

按用户再归因时间筛选的举例如下：

```json
{
  "property_condition": [
    {
      "field": "create_time",
      "type": "user_re_attribute",
      "operator": "RANGE_IN",
      "value": [
        "2026-07-30 00:00:00",
        "2026-07-30 23:59:59"
      ]
    }
  ]
}
```

#### 素材类型（material\_file\_type） [#素材类型material_file_type]

`field` 为 `material_file_type`（素材类型）的条件是一个特殊的分组条件：它本身不直接过滤素材值，而是用来在指定素材类型下继续按素材 ID、素材再归因字段等子条件筛选，因此必须配合 `operator` 为 `has_children`，并通过 `logic` 与 `conditions` 传入子条件。

| 字段           | 取值                   | 描述                                                      |
| ------------ | -------------------- | ------------------------------------------------------- |
| `field`      | `material_file_type` | 素材类型                                                    |
| `type`       | `material`           | 固定为素材类型                                                 |
| `operator`   | `has_children`       | 表示该条件由子条件组成                                             |
| `logic`      | `AND`                | 多个子条件之间的逻辑关系                                            |
| `conditions` | object\[]            | 子条件数组，每个元素为一个完整的查询条件（`field`、`type`、`operator`、`value`） |

`conditions` 中的子条件支持以下类型：

| 子条件 type                | 子条件 field                                             | 说明         |
| ----------------------- | ----------------------------------------------------- | ---------- |
| `material`              | `bytedanceMid1`–`bytedanceMid8`                       | 按素材字段筛选    |
| `material_re_attribute` | `ReAttributeBytedanceMid1`–`ReAttributeBytedanceMid8` | 按素材再归因字段筛选 |

一个素材类型条件可以包含多个子集条件，这些子条件以数组形式传入 `conditions`，由 `logic` 决定它们之间的关系。

#### 按素材筛选 [#按素材筛选]

`type` 传 `material`，`field` 取素材字段；同一请求中可同时传入素材字段条件与 `material_file_type` 的子条件，进一步限定素材。举例如下：

```json
{
  "property_condition": [
    {
      "operator": "IN",
      "field": "bytedanceMid1",
      "type": "material",
      "value": [
        "123"
      ]
    },
    {
      "operator": "has_children",
      "field": "material_file_type",
      "type": "material",
      "logic": "AND",
      "conditions": [
        {
          "field": "bytedanceMid1",
          "type": "material",
          "operator": "EQUALS",
          "value": [
            "111"
          ]
        }
      ]
    }
  ]
}
```

#### 按素材再归因筛选 [#按素材再归因筛选]

素材再归因字段需使用 `type` 为 `material_re_attribute`，`field` 取 `ReAttributeBytedanceMid1`–`ReAttributeBytedanceMid8`。注意 `material_file_type` 节点自身的 `type` 仍为 `material`，只有 `conditions` 中的子条件使用 `material_re_attribute`。举例如下：

```json
{
  "property_condition": [
    {
      "operator": "IN",
      "field": "ReAttributeBytedanceMid1",
      "type": "material_re_attribute",
      "value": [
        "12313"
      ]
    },
    {
      "operator": "has_children",
      "field": "material_file_type",
      "type": "material",
      "logic": "AND",
      "conditions": [
        {
          "field": "ReAttributeBytedanceMid5",
          "type": "material_re_attribute",
          "operator": "EQUALS",
          "value": [
            "111"
          ]
        }
      ]
    }
  ]
}
```

### OrderByObject [#orderbyobject]

如果想在查询时排序，需要传入 `order_by_list` 参数，其中 `order_by_list` 为一个数组，数组中的元素为 `OrderByObject` 类型，`OrderByObject` 中包含两个字段：

* `field`：排序字段，支持的排序字段参考【排序指标】
* `sort`：排序方式，支持的排序方式有：`0`（升序）和 `1`（降序）

`order_by_list` 具有顺序，会优先按照第一个排序字段进行排序，如果第一个排序字段相同，则按照第二个排序字段进行排序，以此类推。

`order_by_list` 举例如下：

优先按照付费次数降序，其次按照付费金额升序排序

```json
[
  {
    "field": "user$pay_count",
    "sort": 1
  },
  {
    "field": "user$pay_amount_sum",
    "sort": 0
  }
]
```

### 排序指标 [#排序指标]

目前支持排序的字段如下，其中字符串按照字符串字母排序，数字按照数字大小排序，时间类型按照时间先后排序：

| 字段                      | 含义        |
| ----------------------- | --------- |
| `ClientID`              | client ID |
| `AdPlatform`            | 媒体平台      |
| `Channel`               | 渠道        |
| `Version`               | 客户端版本     |
| `TurboPromotedObjectID` | 推广活动 ID   |
| `WXOpenID`              | openid    |
| `AdvertiserID`          | 广告账户 ID   |
| `AdAid`                 | 广告 ID     |
| `LatestLoginDay`        | 最近登录日期    |
| `user$pay_amount_sum`   | 用户付费总额    |
| `user$pay_count`        | 用户付费次数    |
| `user$pay_max_amount`   | 用户付费最大金额  |

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

```bash
curl 'https://api-insight.gravity-engine.com/openapi/api/v1/report/user/list/' \
-H 'Content-Type: application/json' \
-H 'Authorization: YOUR_AUTHORIZATION' \
-d '{
  "app_id": 24390285,
  "user_filtering": {
    "create_date_list": [
      "2026-04-02",
      "2026-04-02"
    ]
  },
  "event_filtering": {
    "postback_filtering": [
      {
        "event_type": "activate",
        "status": "0"
      }
    ]
  },
  "sign": "YOUR_SIGN"
}'
```

### 应答参数指标说明 [#应答参数指标说明]

请参考 [用户信息报表应答字段说明](/docs/appendix/user-info-report-metrics)。

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

```json
{
  "data": {
    "page_info": {
      "page": 1,
      "page_size": 20,
      "total_number": 32,
      "total_page": 2
    },
    "list": [
      {
        "CreateTime": "2024-07-23 09:01:40",
        "ClientID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdPlatform": "",
        "Channel": "xxx",
        "Version": 2040,
        "TurboPromotedObjectID": "default_13142548",
        "Name": "oeBZI5MHOLvm-Cf8yK9X0",
        "WXOpenID": "oeBZI5MHOLvm-Cf8yK9X0",
        "AdvertiserID": "",
        "AdAid": "",
        "AdGid": "",
        "AdCid": "",
        "CSite": "",
        "LatestLoginDay": "20240723",
        "user$ad_24h_ltv": 0,
        "user$ad_count": 0,
        "user$ad_ltv": 0,
        "user$ad_max_ecpm": 0,
        "user$brand": "HUAWEI",
        "user$channel": "xxx",
        "user$city": "宜宾市",
        "user$country": "中国",
        "user$first_pay_time": "2024-07-23 10:06:54",
        "user$first_scene": "1055",
        "user$first_visit_time": "2024-07-23 09:53:38",
        "user$gender": "",
        "user$interstitial_ad_24_ltv": 0,
        "user$interstitial_ad_count": 0,
        "user$interstitial_ad_ltv": 0,
        "user$interstitial_ad_max_ecpm": 0,
        "user$manufacturer": "HUAWEI",
        "user$model": "NOH-AN00",
        "user$name": "",
        "user$os": "android",
        "user$pay_amount_sum": 36200,
        "user$pay_count": 13,
        "user$pay_max_amount": 9800,
        "user$province": "四川省",
        "user$reward_ad_24h_ltv": 0,
        "user$reward_ad_count": 0,
        "user$reward_ad_ltv": 0,
        "user$reward_ad_max_ecpm": 0,
        "user$ta_account_id": "",
        "user$ta_distinct_id": "",
        "re_attribute_info": null,
        "device_info": {
          "DeviceId": 15291449,
          "OS": 0,
          "Idfa": "空",
          "Idfv": "BDA32D21-41DD-4098-B0C4-9DDB1F5EFFD2",
          "Caid1": "空",
          "Caid2": "空",
          "Oaid": "空",
          "Imei": "空",
          "AndroidId": "空",
          "Android_Version": "空",
          "Api_Version": 0,
          "Rom": "空",
          "Rom_version": "空",
          "Aspect_Ratio": "空",
          "Phone_Brand": "空",
          "Phone_Model": "空"
        }
      }
    ],
    "total": []
  },
  "extra": null,
  "code": 0,
  "msg": "成功"
}
```