Listings APIListings API
Get API keySign in
GET/api/v4/social/posts/{postId}

Get a social post

Returns one social post with its content, schedule and the live per-channel publish status, link and error.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Path

NameTypeRequiredDescription
postIdstringrequiredPost UUID, the `socialPostId` returned by POST /social/posts or the `socialPostId` of a row from the brand's post list.

Responses

200The post, with per-channel publish state in `connectedChannels`.
Response
{  "data": {    "getSocialMediaPost": {      "name": "Autumn collection launch",      "status": "PUBLISHED",      "initialContent": "Our autumn collection lands today. Solid oak, hand-finished, made two blocks from the shop. Come see it in person this weekend.",      "initialMedia": ["https://cdn.example.com/social/autumn-collection.jpg"],      "initialVideo": [],      "globalPostSchedule": "2026-10-02T13:30:00Z",      "customDataFlag": false,      "approvalState": null,      "actionOn": null,      "comment": null,      "postAutomationId": null,      "connectedChannels": [        {          "id": "b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7",          "platform": "INSTAGRAM",          "socialPlatformId": 2,          "displayName": "Jenny Home",          "userName": "jennyhome",          "userImage": "https://cdn.listingsapi.com/social/channels/b81d5b3c/avatar.jpg",          "status": "SUCCESS",          "liveLink": "https://www.instagram.com/p/CxYz1234abc/",          "reason": null,          "error": null,          "archived": false        },        {          "id": "2d4e6f80-1c33-4b7a-8e05-9a1b2c3d4e5f",          "platform": "FACEBOOK",          "socialPlatformId": 1,          "displayName": "Jenny Home & Co.",          "userName": "jennyhomeco",          "userImage": "https://cdn.listingsapi.com/social/channels/2d4e6f80/avatar.jpg",          "status": "SUCCESS",          "liveLink": "https://www.facebook.com/jennyhomeco/posts/1029384756",          "reason": null,          "error": null,          "archived": false        },        {          "id": "7c5b9a12-8de4-4a31-b0f2-6e3d4c5b8a90",          "platform": "LINKEDIN",          "socialPlatformId": 4,          "displayName": "Jenny Home",          "userName": "jenny-home",          "userImage": null,          "status": "ERROR",          "liveLink": null,          "reason": "Authorization expired",          "error": "The LinkedIn authorization for this channel is no longer valid. Reconnect the channel and post again.",          "archived": false        }      ]    }  }}
401Unauthenticated, missing or invalid API key.
404No post with that ID on this account.

Fetches one post by its UUID, with the content that was composed, the schedule it resolved to, and one entry per targeted channel describing what actually happened on that platform. This is the endpoint you poll after creating a post.

Use case: post-publish verification. Publishing is asynchronous, so POST /social/posts tells you only that the post was accepted. Poll this endpoint with the returned socialPostId and read connectedChannels[]: status: "SUCCESS" with a liveLink means that channel is live, status: "ERROR" with error set means it is not, and why. Stop polling once no channel is still SCHEDULED.

Use case: showing the customer where their post went. Render each connectedChannels[].liveLink as an outbound link so the user can open the published post on the platform itself, and surface error inline on the channels that failed instead of collapsing the whole post to a single failed state.

Reading the status fields

There are two levels of status and they answer different questions.

FieldValuesMeans
statusDRAFT, PENDING, SCHEDULED, PUBLISHED, FAILED, ARCHIVED, REJECTEDThe post as a whole.
connectedChannels[].statusSCHEDULED, SUCCESS, ERROR, ARCHIVEDWhat happened on that one platform.

A post can read PUBLISHED overall while one channel sits at ERROR. Always render from connectedChannels[]; the post-level status is a summary.

Notes.

  • globalPostSchedule is the resolved publish instant in UTC. If you scheduled with scheduleDate + scheduleTime, this is what the brand's timezone resolved those to — a useful check that the zone was what you expected.
  • error is a human-readable message safe to show a customer; reason is the shorter internal label behind it. Neither carries platform tokens or trace IDs.
  • connectedChannels[].id is the connection UUID from the brand's connections, and the value insights requires as socialConnectedChannelId.
  • A channel that reads archived: true was disconnected after the post was created. It will not publish; see disconnect.
  • A channel stuck at ERROR after an authorization lapse needs a fresh connection link, not a retry of the post.
  • For engagement numbers rather than delivery state, call GET /social/posts/{postId}/insights.
  • To list a brand's posts rather than fetch one, use GET /social/brands/{brandId}/posts.
Request
curl -X GET 'https://listingsapi.com/api/v4/social/posts/<postId>' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground