Posts

List posts

Returns posts across every workspace you belong to, teammates' posts included, per your role in each workspace. Pass workspace_id to scope to one workspace. A brand-locked seat only sees posts in its assigned brands. A draft any editor skipped in the Content Engine review queue is always excluded, even when you explicitly filter status=draft. Filter a calendar window with scheduled_from and scheduled_to (plain dates are read in timezone). Results are paged: total is the exact count for the filters, and has_more / next_offset tell you whether to call again. The order is total (sort field, then created_at, then id), so offset pages never skip or repeat a post. For per-day, per-account, or per-brand totals use GET /api/v1/posts/counts.

get/api/v1/posts

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/posts
  • Auth: HTTP bearer

Query parameters

statusstring
platformstring
account_idstring

Filter to a specific connected social account.

workspace_idstring

Filter to posts in a specific workspace.

scheduled_fromstring
Example:2026-10-01

Start of the scheduled range, inclusive. A plain date (YYYY-MM-DD) is midnight in timezone; an ISO 8601 date-time without an offset is read in timezone; one with an offset is exact. Invalid values answer 400 with code: "invalid_scheduled_from".

scheduled_tostring
Example:2026-10-31

End of the scheduled range. A plain date includes that whole day in timezone; a date-time is exclusive. Must be after scheduled_from (code: "invalid_scheduled_range").

timezonestring
Example:Europe/London

IANA time zone used to read plain dates in the scheduled range. Invalid values answer 400 with code: "invalid_timezone".

order'asc' | 'desc'

Sort direction for every sort key (case-insensitive). asc reads a calendar oldest first. Invalid values answer 400 with code: "invalid_order".

limitinteger

Posts per page. Values above 200 are capped at 200.

offsetinteger

Posts to skip. Use next_offset from the previous page.

updated_sincestring date-time

Only return posts updated at or after this timestamp.

created_sincestring date-time

Only return posts created at or after this timestamp.

sort_by'scheduled_at' | 'updated_at' | 'created_at'

Sort field for the returned posts.

approval_status'none' | 'pending_client' | 'approved' | 'changes_requested' | 'rejected'

Filter by client review approval status. pending_client means the post is waiting on the client. Invalid values answer 400 with code: "invalid_approval_status".

approval_waiting_on'client' | 'team'

client matches pending_client. team matches changes_requested and rejected. A value that does not overlap approval_status answers 400 with code: "approval_filter_conflict".

brand_idstring uuid

Filter to posts assigned to a specific brand/client (the id from GET /api/v1/brands), matching each post's brand_id. A non-UUID value answers 400 with code: "invalid_brand_id".

Response

Posts fetched successfully

totalinteger required

Exact number of posts matching every filter, across all pages.

limitinteger required
offsetinteger required
has_moreboolean required

True while offset + posts.length is below total. Keep paging until it is false before drawing conclusions about totals.

next_offsetinteger nullable required

The offset of the next page, or null on the last page.

order'asc' | 'desc' required

Example response

{
  "posts": [
    {
      "id": 971,
      "content": "Searching for the best teeth whitening device?",
      "scheduled_at": "2026-03-11T09:45:00.000Z",
      "social_account_id": 123,
      "media_urls": [
        "https://assets.poster.ly/users/123/post-1.jpg"
      ],
      "status": "scheduled",
      "post_type": "carousel",
      "created_at": "2026-03-10T09:45:00.000Z",
      "updated_at": "2026-03-10T09:45:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "order": "desc"
}

Changes

No recorded changes to this operation across all 1 revision of this API.