# 用户信息报表 > 来源：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` 为再归因字段（例如 `create_time` 表示筛选再归因时间），`type` 为 `user_re_attribute`（用户再归因属性），`operator` 为查询操作符，`value` 为过滤值数组。举例如下： ```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" ] } ] } ``` ### 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: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfa2V5IjoiYmY5YjNhZjU2ZDNkNGM5ZDkyZTFhYDYxMGQwNWQifQ.AfTDDjv4xQCI79Pyxw4pWSGIwqtwaIGOEwterZgI-q0' \ -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": "4456c2f50c06811d6964eacb3abf" }' ``` ### 应答参数指标说明 [#应答参数指标说明] 请参考 [用户信息报表应答字段说明](/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": "成功" } ```