> ## Documentation index
> Fetch the complete documentation index at: https://dash.robopost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List and read posts

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](https://dash.robopost.app/docs/api/authentication.md).

## Read one post

```bash
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](https://dash.robopost.app/docs/api/edit-and-delete-posts.md) the post. A post of another
team, or an ID that doesn't exist, answers `404 POST_NOT_FOUND`.

## List posts

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

```json
{ "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](https://dash.robopost.app/docs/api/changes-and-webhooks.md)) |
| `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](https://dash.robopost.app/docs/posts/drafts-and-approvals.md) 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](https://dash.robopost.app/docs/channels/posting-limits.md) 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

```json
"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?](https://dash.robopost.app/docs/posts/why-did-my-post-fail.md)
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`.

## Next

[Edit and delete posts](https://dash.robopost.app/docs/api/edit-and-delete-posts.md)