GET/social-posts

Query and paginate your social posts with filters. Supports filtering by IDs, platforms, statuses, and date ranges.

https://api.postfa.st/Auth: pf-api-keyRate limit: 200 requests per hour

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. When you pass ids, results follow this order, not the order the IDs were supplied.

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 platforms, statuses, from, and to. An invalid (non-UUID) value returns 400; an empty ids means no filter (the normal paginated list), not zero results.

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).

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.

Query parameters

pageintegeroptionaldefault 0

Page number (0-based indexing).

limitintegeroptionaldefault 20

Number of items per page (min 1, max 50).

idsstringoptional

Comma-separated post UUIDs to fetch a specific set of posts (max 100, each a UUID v4). Workspace-scoped and AND-ed with the filters below.

platformsstringoptional

Comma-separated platform values, e.g. FACEBOOK,INSTAGRAM.

FACEBOOKINSTAGRAMXTIKTOKLINKEDINYOUTUBEBLUESKYTHREADSPINTERESTTELEGRAMGOOGLE_BUSINESS_PROFILE
statusesstringoptional

Comma-separated status values.

DRAFTSCHEDULEDPUBLISHEDFAILED
fromISO 8601optional

Start date filter in UTC (inclusive, filters by scheduledAt).

toISO 8601optional

End date filter in UTC (inclusive, filters by scheduledAt).

Response

200 OK A paginated object with data[] posts plus totalCount and pageInfo.