# 查询发布记录

- API 版本：1.10.0
- 最后更新：2026-09-29
- 服务地址：`https://api.ailingtu.com`
- 网页文档：[查询发布记录](/openapi/post-records)
- 完整接口约束：[JSON Schema](/openapi/operations/listCreatorPosts.json)
- 接口发现：[接口索引](/openapi/operations/index.json)

## GET /v1/creator/post/pageList

接口标识：`listCreatorPosts`

分页查询 TikTok 与 TikTok Shop 发布记录，用于跟踪任务状态，并读取平台作品 ID、失败原因、素材、商品和排期信息。

鉴权：请求头 `x-api-key: <YOUR_API_KEY>`；密钥仅保存在服务端。

成功判断：HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `pageSize` | query | integer | 是 | 每页数量，最大 200 |
| `pageNumber` | query | integer | 是 | 页码，从 1 开始 |
| `beginTime` | query | integer | 否 | 计划发布时间开始（含），13 位毫秒时间戳；可单独传。示例：1789056000000 |
| `endTime` | query | integer | 否 | 计划发布时间结束（含），13 位毫秒时间戳；可单独传。示例：1789142399999 |
| `status` | query | WAITING_SUBMIT \| SUBMITTING \| PRE_CHECK_SUBMITTING \| PRE_CHECK \| PRE_CHECK_PASSED \| PRE_CHECK_REJECTED \| PENDING \| PROCESSING \| SUCCESS \| COMPLETED \| FAILED \| CANCELLED \| SUBMIT_FAILED | 否 | 发布状态 |
| `postId` | query | string | 否 | 灵途发布任务 ID |
| `title` | query | string | 否 | 发布标题或文案关键词 |
| `creatorUsername` | query | string | 否 | TikTok 达人用户名 |
| `platform` | query | TIKTOK \| TIKTOK_SHOP \| TIKTOK_BUSINESS | 否 | 发布平台 |
| `managerIds` | query | integer[] | 否 | 账号管理人 ID；多个值重复传递 Query 参数 |
| `noManager` | query | boolean | 否 | 是否仅查询未分配管理人的账号 |

### 成功响应

```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 100,
        "postId": "post_xxx",
        "platform": "TIKTOK_SHOP",
        "title": "Summer Sale 2026 #summer",
        "videoUrl": "https://cdn.ailingtu.com/media/video.mp4",
        "coverUrl": "https://cdn.ailingtu.com/media/video-cover.jpg",
        "reason": null,
        "remark": null,
        "platformPostId": "7541234567890123456",
        "scheduledAt": 1784896665989,
        "scheduledTz": "America/New_York",
        "publishedAt": 1784896765989,
        "status": "COMPLETED",
        "creatorUsername": "shop_creator",
        "createdByName": "Operations Team",
        "productInfo": {
          "productId": "1732280564607717841",
          "title": "Summer Vibes Cord",
          "source": "SHOP"
        },
        "productLinks": null,
        "musicInfo": {
          "id": "7567668059796720391",
          "title": "original sound",
          "author": "Ivan",
          "duration": "15"
        },
        "materialType": "VIDEO",
        "mediaType": "VIDEO",
        "shopMaterialId": null
      }
    ],
    "total": 1,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1
  },
  "message": "success"
}
```

### 响应字段

以下列出主要层级；完整结构、联合类型及校验规则以接口 JSON Schema 为准。必填指字段所在对象中的约束。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | integer | 是 | 固定值：0 |
| `message` | string | 否 | — |
| `data` | object | 是 | — |
| `data.list` | object[] | 是 | — |
| `data.list[].id` | union | 是 | — |
| `data.list[].postId` | string | 是 | — |
| `data.list[].platform` | string | 是 | 可选值：TIKTOK_SHOP、TIKTOK、TIKTOK_BUSINESS |
| `data.list[].title` | string | 是 | — |
| `data.list[].videoUrl` | string \| null | 否 | — |
| `data.list[].coverUrl` | string \| null | 否 | — |
| `data.list[].reason` | string \| null | 否 | — |
| `data.list[].remark` | string \| null | 否 | — |
| `data.list[].platformPostId` | string \| null | 否 | — |
| `data.list[].scheduledAt` | union | 否 | — |
| `data.list[].scheduledTz` | string \| null | 否 | — |
| `data.list[].publishedAt` | integer \| string \| null | 否 | 发布时间，响应可能为时间戳或日期字符串。 |
| `data.list[].status` | string | 是 | 可选值：WAITING_SUBMIT、SUBMITTING、PRE_CHECK_SUBMITTING、PRE_CHECK、PRE_CHECK_PASSED、PRE_CHECK_REJECTED、PENDING、PROCESSING、SUCCESS、COMPLETED、FAILED、CANCELLED、SUBMIT_FAILED |
| `data.list[].creatorUsername` | string | 是 | — |
| `data.list[].createdByName` | string \| null | 否 | — |
| `data.list[].productInfo` | union | 否 | — |
| `data.list[].productLinks` | union | 否 | — |
| `data.list[].musicInfo` | union | 否 | — |
| `data.list[].materialType` | string \| null | 否 | — |
| `data.list[].mediaType` | string \| null | 否 | — |
| `data.list[].shopMaterialId` | union | 否 | — |
| `data.list[].snapshot` | object \| null | 否 | 创建发布任务时保存的原始媒体快照；老数据或无文件快照时为 null。PHOTO 会返回全部源文件。 |
| `data.list[].snapshot.sourceFiles` | object[] | 否 | 源文件列表，VIDEO 为单个文件，PHOTO 按原始图序返回全部文件。 |
| `data.total` | integer | 是 | — |
| `data.pageNumber` | integer | 是 | — |
| `data.pageSize` | integer | 是 | — |
| `data.totalPages` | integer | 是 | — |
| `timestamp` | integer | 否 | 响应时间戳，单位毫秒。 |

### 接入说明与限制

- 最简请求只需 pageSize 与 pageNumber，例如：?pageSize=10&pageNumber=1。
- 发布创建成功不代表平台发布完成；请保存 postId，并通过本接口查询最终状态。
- SUCCESS、COMPLETED 和 PRE_CHECK_PASSED 表示成功类状态；FAILED、SUBMIT_FAILED 和 PRE_CHECK_REJECTED 表示失败类状态。
- beginTime 和 endTime 同时传入时，开始不能晚于结束，跨度最多 90 天。snapshot 为原始素材快照，历史记录可为 null；图文保留全部源文件顺序。

### 错误处理

| HTTP | 说明 |
|---|---|
| 400 | 请求参数或请求体无效，请修正后重试。 |
| 401 | API 密钥缺失或无效，请检查 x-api-key。 |
| 403 | API 密钥没有此接口的调用权限。 |
| 429 | 请求过于频繁，请采用指数退避重试。 |
| 500 | 服务端发生错误；对于暂时性故障采用指数退避重试。 |

业务 code 非零时也应按失败处理。不要对参数、权限或授权错误盲目重试。创建发布或生成任务超时后先查询原任务，避免重复创建。

### 相关接口

- [带货视频立即发布](/openapi/submit-post) · [Markdown](/openapi/operations/submitCreatorPost.md)
- [编辑发布记录](/openapi/update-post) · [Markdown](/openapi/operations/updateCreatorPost.md)
- [取消发布](/openapi/cancel-post) · [Markdown](/openapi/operations/cancelCreatorPost.md)