列出品牌的貼文 | Listings API

參數

路徑

名稱	類型	必填	說明
brandId	string	必填	Brand UUID whose posts should be listed.

查詢

名稱	類型	必填	說明	預設值
filters	string	選填	JSON-encoded filter object. Fields: `name` (substring match on the post's internal name), `platforms` (array of the platform enum), `status` (array of `DRAFT`, `PENDING`, `SCHEDULED`, `PUBLISHED`, `FAILED`, `ARCHIVED`, `REJECTED`), `startDate` and `endDate` (`YYYY-MM-DD`, filtering on the post's schedule in the brand's timezone), `socialConnectedChannelId` (one connection), `approvalState` (array of workflow states), `viewMode` (string) and `filterByUser` (boolean, defaults to false).	—
page	integer	選填	1-based page number. Defaults to 1.	—
size	integer	選填	Rows per page. Defaults to 20.	—
fetchPostContent	boolean	選填	When `true`, each row carries its full `content` object. Leave it off for a lighter list.	—

回應

200A page of posts plus `pageInfo` for paging.

Response

{  "data": {    "getSocialMediaPostByList": {      "socialPosts": [        {          "socialPostId": "c47a1e58-2b93-4f10-a6d7-58e0c9b12345",          "name": "Autumn collection launch",          "status": "PUBLISHED",          "platforms": ["INSTAGRAM", "FACEBOOK", "LINKEDIN"],          "socialPlatformIds": [2, 1, 4],          "socialProfileDetailsId": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "createdAt": "2026-09-28T14:02:11Z",          "createdBy": 40122,          "author": "Dana Reyes",          "approver": null,          "approvalState": null,          "actionOn": null,          "actionBy": null,          "publishedOn": "2026-10-02T13:30:04Z",          "postAutomationId": null,          "content": {            "message": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop.",            "images": ["https://cdn.example.com/social/autumn-collection.jpg"],            "video": [],            "liveLink": "https://www.instagram.com/p/CxYz1234abc/",            "boosted": false          },          "connectedChannels": [            {              "id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",              "platform": "INSTAGRAM",              "displayName": "Jenny Home",              "status": "SUCCESS",              "liveLink": "https://www.instagram.com/p/CxYz1234abc/",              "error": null            }          ]        }      ],      "pageInfo": {        "total": 64,        "hasNextPage": true,        "totalEngagementPosts": 41,        "totalPublishedPosts": 47      }    }  }}

401Unauthenticated, missing or invalid API key.

404No brand with that ID on this account (`SY95043`).

列出單一品牌的貼文，依時間由新到舊排序，並可依名稱、平台、狀態、核准狀態及排程時間範圍篩選。每筆資料都包含足以呈現行事曆或動態消息的資訊，無須為每篇貼文再次呼叫。

使用案例：內容行事曆。使用 filters={"status":["SCHEDULED"],"startDate":"2026-10-01","endDate":"2026-10-31"} 篩選，並將每筆資料放在其 publishedOn 對應的時間；若貼文尚未發布，則放在您送出的排程時間。為每個項目提供串接至 POST /social/posts/cancel 的取消操作，並使用 GET /social/posts/{postId} 開啟詳細檢視。

使用案例：失敗貼文巡查。每晚使用 filters={"status":["FAILED"]} 逐一檢查各個品牌，並針對傳回的資料列發出警示。connectedChannels[].error 會告訴您哪個平台拒絕發布及其原因；回報授權已過期的管道需要新的連線連結，而不是重試。

注意事項。

socialPostId 是取得、洞察資料和取消端點接受的一般 UUID。
篩選條件以單一 JSON 編碼字串的形式放在 filters 查詢參數中傳送，而不是作為個別參數傳送。請將該字串做 URL 編碼。
分頁採用位移量方式（page／size）；pageInfo.total 是符合條件的貼文總數，而不是此頁的筆數。totalPublishedPosts 和 totalEngagementPosts 是涵蓋整個品牌的計數，適合用於儀表板資訊方塊。
資料列僅包含貼文層級的狀態。若要查看解析後的確切排程時間及各管道的結果，請使用 GET /social/posts/{postId} 開啟貼文。
startDate 和 endDate 依貼文排程篩選，並以品牌的時區解讀，與解讀 scheduleDate／scheduleTime 時使用的時區相同。
在至少一個管道成功發布之前，publishedOn 都是 null。若貼文的所有管道都發布失敗，則會保留 publishedOn: null，且 status 為 FAILED。
只有採用貼文核准工作流程的帳戶才會填入 approvalState、approver、actionOn 和 actionBy；否則這些欄位會維持 null。
僅在您要呈現貼文內文時設定 fetchPostContent=true；資料量較小的預設值已足以呈現行事曆。