List and read posts

On this page

Every post of your team can be read through the API, whatever created it: the dashboard, the API, a CSV import or an automation. Removed and failed posts stay readable, so your integration can always find out what happened to a post it created.

You need: an API key.

Read one post

curl https://public-api.robopost.app/v1/scheduled_posts/8c1f2a40-… \
  -H "Authorization: Bearer $ROBOPOST_API_KEY"

The response is the post, and its ETag header is its current revision (for example "4"). Send it back as If-Match when you edit or delete the post. A post of another team, or an ID that doesn't exist, answers 404 POST_NOT_FOUND.

List posts

curl "https://public-api.robopost.app/v1/scheduled_posts?status=scheduled&channel_id=<id>&limit=50" \
  -H "Authorization: Bearer $ROBOPOST_API_KEY"

{ "scheduled_posts": [ { "id": "…", "status": "scheduled", "…": "…" } ], "next_cursor": "WyIyMDI2…", "has_more": true }

Pass cursor=<next_cursor> to get the next page, until has_more is false. The cursor keeps your place even when posts are added in the meantime.

Parameter	Meaning
`status`	One or more statuses (repeat the parameter): see below
`channel_id`, `social_network`	Only these channels or networks
`schedule_at_from`, `schedule_at_to`	Scheduled time range
`published_at_from`, `published_at_to`	Publication time range
`created_at_from`, `created_at_to`	Creation time range
`updated_since`	Changed since this time (for a full sync use the change feed)
`post_collection_id`	Posts of one collection
`idempotency_key`	Posts created by the request sent with this key
`include_deleted`	`true` to include removed posts
`sort`, `order`	`schedule_at` (default), `created_at` or `updated_at`; `asc` (default) or `desc`
`limit`, `cursor`	Page size (1–100, default 50) and position

Post statuses

`status`	Meaning
`draft`	Saved, not scheduled
`pending_approval`, `approved`	In the approval workflow
`scheduled`	Waiting for its time
`preparing_media`	Media from a URL is being downloaded
`publishing`	Being sent to the network right now
`published`	Live on the network: see `platform.post_url`
`failed`	Not published: see `failure`
`in_collection`	Waiting in a collection

state holds the internal name of the same thing (SCHEDULED, POSTED, ERROR…) if you need it.

What a post contains

Field	Meaning
`id`, `revision`	Stable ID, and a number that goes up with every change
`channel_id`, `channel`, `social_network`	Where it posts (`channel` has the name and network)
`source`	`api`, `dashboard`, `csv_import`, `automation` or `collection`
`text`, `first_comment`, `made_with_ai`, `settings`	The content and the per-network settings
`schedule_at`, `timezone`	When it's due (UTC)
`publishing_started_at`, `published_at`	When publishing started and finished
`platform.post_id`, `platform.post_url`	The post's own ID and address on the network
`failure`	Why it failed, and what to do: see below
`media`	Media IDs or URLs, and `ready`
`recurrence`	Repeat settings
`waiting_for_daily_limit`	`true` while the channel's daily limit holds it back
`analytics`	Impressions, engagements, likes, comments, shares, saves, rate, `last_synced_at`
`is_deleted`, `deleted_at`, `deleted_by`, `deletion_reason`	Whether, when, by whom and why it was removed
`platform_deletion`	The result of asking to delete it on the network too
`hidden_in_dashboard`	The dashboard no longer shows it (failed posts are hidden there after a few minutes)
`created_at`, `updated_at`	Record times

Failures

"failure": {
  "code": "CHANNEL_AUTH_ERROR",
  "message": "The channel needs to be reconnected.",
  "retryable": true,
  "action": "reconnect_channel",
  "failed_at": "2026-11-06T19:00:12.000Z"
}

retryable says whether the same post can be scheduled again once action is done: reconnect_channel, upgrade_plan_or_wait_for_reset, buy_x_credits, retry_later, fix_the_media, fix_the_account, change_the_content or check_the_network_before_posting_again (the network may have published it despite the error: look before posting again). Why did my post fail? explains each cause.

Deletions

deletion_reason is deleted_by_user (in the dashboard; deleted_by is user:<id>), deleted_via_api (deleted_by is api_key:<id>), channel_removed, account_frozen, subscription_inactive, missing_required_media (a YouTube, TikTok or Pinterest post without the media the network needs), media_download_failed or removed (older posts removed before reasons were recorded). A failed post the dashboard hides is not deleted: it keeps status: failed with hidden_in_dashboard: true.

Edit and delete posts