GET/social-posts

Implementation notes

Pagination: request page=0 for the first page. The response shows page: 1 in pageInfo (a 1-based display number).

Limits: maximum 50 posts per page, even if a higher limit is requested. The ids filter is the one exception: the page expands to return every requested ID (up to 100), so an ids request is not capped at 50.

Sorting: fixed to scheduledAt ascending, then id, so paging through a list that is not changing never repeats or skips a post. When you pass ids, results follow this order, not the order the IDs were supplied.

Deleting while you page: pages are offsets, so deleting posts shifts later posts onto pages you have already read, and they get skipped. To delete everything that matches a filter, re-read page=0 until it comes back empty (see POST /social-posts/bulk-delete).

Empty results: when nothing matches, data is [] and totalCount is null, not 0.

Filter by IDs: the ids filter is workspace-scoped, so IDs that do not exist or belong to another workspace are silently omitted, and it is AND-ed with socialMediaIds, platforms, statuses, from, and to. Omit the parameter for no filter: an empty value (ids=), a trailing comma, or a non-UUID returns 400.

Filter by accounts: socialMediaIds is workspace-scoped and AND-ed with the other filters, so account ids from another workspace match nothing (200 with no posts). The same rules as ids apply: up to 100 UUIDs, and an empty value, a trailing comma, or a non-UUID returns 400. Omit it for all accounts.

Unknown query parameters are ignored, not rejected. The singular socialMediaId is not a filter, so ?socialMediaId=... returns every account's posts: use socialMediaIds.

Case sensitivity: platforms and statuses values are case-insensitive (automatically uppercased).

Error information: failed posts include lastError with a user-friendly message and a platform error code (e.g. "200", "2207027"); it is null otherwise.

First comment: each post includes firstComment (the comment text, or null) and firstCommentError (an error object if the first comment failed after up to 3 attempts, or null).

Post settings: each post includes controls, the settings stored on the post that decide its format, visibility, or topic: threadsTopicTag, instagramPublishType, facebookContentType, tiktokIsDraft, and youtubePrivacy, each null when unset. Posts created over the API carry every platform's defaults, so a Threads post also shows instagramPublishType: "TIMELINE". Read only the fields for the post's own platform (match socialMediaId against GET /social-media/my-social-accounts).

Workspace isolation: results are automatically filtered to the workspace tied to the API key.

Next page check: use pageInfo.hasNextPage to determine whether more pages are available.