list_posts
Retrieve and filter social posts across workspaces by status, platform, account, brand, group, release, approval, and scheduled date range; get paginated results or exact daily counts.
Instructions
Posts in your workspaces, teammates' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to. view=list (default): posts filtered by status (draft, scheduled, publishing, processing, awaiting_tiktok_publish, awaiting_manual, published, failed, paused, paused_due_to_token, paused_due_to_billing, or missed), platform, account_id, workspace_id, brand_id, group_id, release_id, approval_status, approval_waiting_on, and a scheduled date range: scheduled_from (inclusive) and scheduled_to (a plain date includes that whole day), read in timezone (IANA, default UTC; also the zone times are shown in). status=missed is posts that failed, scheduled posts whose scheduled time is already past, and posts a publishing pause held past their time. group_id matches the caller group (including post_group_id). release_id matches that release only. Returns limit posts (default 20, max 200) starting at offset; with a date range the order defaults to oldest first (order=asc|desc). The output always says whether every matching post was shown. If it says more are available, call again with the offset it gives and keep paging until all are shown before drawing any conclusion about totals, gaps, or how busy a client is. view=counts (scheduled_from and scheduled_to required, up to 366 days): exact totals per day, status, account, and brand for the same filters (limit, offset, and order are ignored); use it for "how many" or "is this month full" questions. Each post includes approval.pending_client_approval.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | list (default): the posts. counts: totals (needs scheduled_from and scheduled_to). | |
| limit | No | Posts per page (default 20, max 200). Ignored by view=counts. | |
| order | No | asc (oldest first) or desc (newest first). Default asc with a date range, otherwise desc. Ignored by view=counts. | |
| offset | No | Matching posts to skip; use the offset the previous page gives. Ignored by view=counts. | |
| status | No | Stored post status (draft, scheduled, publishing, processing, awaiting_tiktok_publish, awaiting_manual, published, failed, paused, paused_due_to_token, paused_due_to_billing, or missed). paused_due_to_token is a reconnect pause and paused_due_to_billing is a billing pause. missed: failed, still scheduled after the scheduled time, or held by a publishing pause past it. | |
| brand_id | No | Filter to posts assigned to a specific brand/client (the id from list_brands). | |
| group_id | No | Caller group id. Matches api_group_id, group_id, and post_group_id. | |
| platform | No | Filter by platform: instagram, facebook, tiktok, twitter, linkedin, youtube, pinterest, threads, google_business, telegram, bluesky, discord, slack, mastodon, devto, hashnode, wordpress, lemmy. | |
| timezone | No | IANA time zone such as Europe/London for reading plain dates and showing times. Default UTC. | |
| account_id | No | Filter to a specific social account ID (from list_accounts). | |
| release_id | No | Caller release id. Matches release_id only. | |
| scheduled_to | No | End of the scheduled range: a plain date (2026-10-31) includes that whole day; an ISO date-time is exclusive. | |
| workspace_id | No | Filter to posts in a specific workspace (get IDs via whoami). | |
| scheduled_from | No | Start of the scheduled range, inclusive: a date (2026-10-01) or an ISO date-time. Plain dates and times without an offset are read in timezone. | |
| approval_status | No | Filter by client review approval status. pending_client means the post is waiting on the client. | |
| approval_waiting_on | No | client: approval_status pending_client. team: changes_requested or rejected. Conflicts with a non-overlapping approval_status. |