# 推广活动列表 > 来源：https://help.gravity-engine.com/docs/server-integration/other-apis/promoted-object-list > 通过 Gravity Engine OpenAPI 分页查询推广活动，了解应用与项目范围、活动筛选、分页参数、请求示例及返回字段。 此接口用于分页查询指定应用或项目下的引力推广活动，支持按活动 ID、名称、状态、创建人及创建日期筛选。 ## 接入准备 [#接入准备] 在[引力后台－引力开发者](https://web.gravity-engine.com/#/manage/develop)申请开发者应用，审核通过并启用后，获取 `app_key`。所在主体需已开通 OpenAPI 功能；请求只能操作当前主体有权限的应用。 `app_key` 是开发者应用的凭证；请求中的 `app_id` 是引力业务应用 ID，两者用途不同。业务应用 ID 可通过[应用信息查询](/docs/server-integration/other-apis/app-info)获取。 ## 认证方式 [#认证方式] | Header | 类型 | 必填 | 说明 | | --------------- | ------ | -- | ---------------------------------------------------------------------------------- | | `Authorization` | string | 是 | 按[签名生成](/docs/server-integration/request-signing)生成的 JWT 字符串，直接填写，不添加 `Bearer ` 前缀 | | `Content-Type` | string | 是 | `application/json` | 将本次实际发送的全部 body 参数（不含 `sign`）用于生成 `sign`，再使用 `sign` 与 `app_key` 生成 `Authorization`。修改任何参数后都需要重新生成两者。以下示例中的 ID、签名、认证字符串和返回数据均为示意值，调用时请替换。 ## 接口信息 [#接口信息] * 请求地址：`https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/list/` * 请求方法：`POST` * 请求格式：JSON body。分页与筛选参数均放在 body 中。 * 默认排序：按创建时间倒序；不支持自定义排序。 ### body 参数 [#body-参数] | 参数名 | 必填 | 类型 | 说明 | | -------------- | ---- | --------- | -------------------------------------------------------------------- | | `app_id` | 条件必填 | int | 查询单个应用时填写引力业务应用 ID | | `app_ids` | 条件必填 | string | 查询多个应用时填写整数 ID 数组的 JSON 字符串，例如 `"[12345678,23456789]"`；不可直接传 JSON 数组 | | `project_id` | 条件必填 | int | 查询项目下有权限的应用时填写项目 ID | | `many_meaning` | 否 | string | 同时匹配活动 ID（精确）或活动名称（包含） | | `page` | 否 | int | 页码，从 `1` 开始，默认 `1`，最大 `2000`；超出最大值按 `2000` 处理 | | `page_size` | 否 | int | 每页条数，默认 `100`，最大 `5000`；超出最大值按 `5000` 处理 | | `filters` | 否 | object\[] | 筛选条件数组，结构见下表；省略表示不附加筛选条件 | | `sign` | 是 | string | 本次请求的签名，参考[签名生成](/docs/server-integration/request-signing) | `app_id`、`app_ids`、`project_id` 至少选择一种查询范围。传入非零 `project_id` 时，以项目内有权限的应用为准；否则，优先使用非空 `app_ids`，再使用 `app_id`。建议一次只使用一种范围参数。`page` 和 `page_size` 必须为正整数。 ### 筛选条件 [#筛选条件] 每个条件包含 `field`（字段名）、`operator`（数字操作符）和 `values`（取值数组）；多个条件按 AND 组合。支持以下字段： | field | operator | values 类型与数量 | 说明 | | ---------------------------- | -------- | ---------------- | --------------------------------------------------------- | | `turbo_promoted_object_id` | `1` | string\[]，恰好 1 项 | 活动 ID 精确匹配 | | `turbo_promoted_object_name` | `8` | string\[]，恰好 1 项 | 活动名称包含指定文本 | | `create_user_id` | `6` | int\[]，1～1000 项 | 创建人 ID 在指定集合内 | | `operator_id` | `6` | int\[]，1～1000 项 | 操作人 ID 在指定集合内 | | `create_time` | `7` | string\[]，恰好 2 项 | 创建日期范围，例如 `["2026-10-01", "2026-10-17"]`，格式为 `YYYY-MM-DD` | | `state` | `1` | int\[]，恰好 1 项 | 状态：`1` 启用、`2` 关停 | `values` 即使只有一个值也必须是数组。不要直接在 body 顶层传活动名称或 `state` 来代替 `filters`。未传 `state` 条件时，列表包含启用及关停的活动。 ### 请求示例 [#请求示例] 查询指定应用下名称包含“秋季”、状态为启用的推广活动： ```bash curl --request POST 'https://api-insight.gravity-engine.com/openapi/api/v1/user/promoted_object/list/' \ --header 'Authorization: YOUR_AUTHORIZATION' \ --header 'Content-Type: application/json' \ --data-raw '{ "app_id": 12345678, "page": 1, "page_size": 100, "filters": [ {"field": "turbo_promoted_object_name", "operator": 8, "values": ["秋季"]}, {"field": "state", "operator": 1, "values": [1]} ], "sign": "YOUR_SIGN" }' ``` 多应用查询时，将上述 `app_id` 替换为 `"app_ids": "[12345678,23456789]"`，并重新生成签名和认证字符串。 ## 返回结果 [#返回结果] ### 应答示例 [#应答示例] ```json { "data": { "page_info": { "page": 1, "page_size": 100, "total_number": 1, "total_page": 1 }, "list": [ { "app_id": 12345678, "turbo_promoted_object_id": "a1b2c3d4e5f6g7h8", "turbo_promoted_object_name": "秋季推广活动", "callback_url": "", "redirect_url": "", "remark": "秋季投放", "state": 1, "create_time": "2026-10-17 10:00:00", "modify_time": "2026-10-17 10:00:00", "create_user_id": 10001, "create_user_name": "管理员", "operator_id": 10001, "operator_name": "管理员", "update_user_id": 0, "update_user_name": "" } ] }, "extra": { "error": "", "request_id": "0123456789abcdef0123456789abcdef" }, "code": 0, "msg": "成功" } ``` ### 返回字段 [#返回字段] | 字段 | 类型 | 说明 | | ----------------------------- | --------- | ---------------------- | | `code` | int | 外层业务状态码，`0` 表示外层处理成功 | | `msg` | string | 状态描述 | | `extra.error` | string | 错误描述，正常时为空字符串 | | `extra.request_id` | string | 请求标识，排查问题时请提供 | | `data.list` | object\[] | 当前页推广活动列表，无匹配记录时为 `[]` | | `data.page_info.page` | int | 当前页码 | | `data.page_info.page_size` | int | 实际每页条数 | | `data.page_info.total_number` | int | 匹配的记录总数 | | `data.page_info.total_page` | int | 总页数，无记录时为 `0` | `data.list` 中每个对象包含以下字段，时间按北京时间（UTC+8）返回： | 字段 | 类型 | 说明 | | ------------------------------------- | ------------ | --------------------------------- | | `app_id` | int | 所属引力业务应用 ID | | `turbo_promoted_object_id` | string | 系统生成的 16 位推广活动 ID | | `turbo_promoted_object_name` | string | 推广活动名称 | | `callback_url` | string | 回调链接；未设置时为空字符串 | | `redirect_url` | string | 重定向地址；未设置时为空字符串 | | `remark` | string | 备注 | | `state` | int | 活动状态：`1` 启用、`2` 关停 | | `create_time` | string | 创建时间，格式 `YYYY-MM-DD HH:mm:ss` | | `modify_time` | string | 最后修改时间，格式 `YYYY-MM-DD HH:mm:ss` | | `create_user_id` / `create_user_name` | int / string | 创建人 ID / 名称 | | `operator_id` / `operator_name` | int / string | 操作人 ID / 名称 | | `update_user_id` / `update_user_name` | int / string | 最后更新人 ID / 名称；尚未更新时通常为 `0` / 空字符串 | ## 调用注意事项 [#调用注意事项] * 根据 `data.page_info.total_page` 逐页查询；修改 `page` 后重新生成 `sign` 和 `Authorization`。超出结果总页数时，`data.list` 为空。 * 同时检查 `code`、`extra.error` 及 `data` 结构。当前接口在部分分页、筛选校验失败场景下，可能仍返回外层 `code=0`，且不包含具体错误；缺少 `data.list` 或 `data.page_info` 时应视为异常。空列表也可能由错误筛选触发，不能仅凭 `code=0` 判断筛选条件有效。 * 缺少认证信息、签名错误、开发者应用不可用或请求被限流时，请检查 `code`、`msg` 和 `extra.error`。限流额度以开发者应用实际配置为准；遇到限流请降低调用频率并退避重试。 * 如需新建活动，请使用[推广活动创建](/docs/server-integration/other-apis/promoted-object-create)。