# GET /posts

> List recent Botdoor posts or get one post with per-account status, live URLs and errors. Polling and settled.

Source: https://docs.botdoor.co/api/posts-read/

`GET /posts` lists recent posts, newest first (`?limit=` 1–100, default 20). `GET /posts/{id}` returns one. MCP tools: `list_posts`, `get_post`.

```bash
curl https://botdoor.co/api/v1/posts/5e7a… -H "Authorization: Bearer $BOTDOOR_KEY"
```

## The post object

```json
{"post": {
  "id": "5e7a…", "status": "published", "settled": true, "error": null, "errorCode": null,
  "content": "Fresh sourdough at 7am", "agent": "content-agent",
  "createdAt": "2026-10-11T19:58:00.000Z", "scheduledFor": "2026-10-11T20:00:00.000Z", "publishedAt": "2026-10-11T20:00:04.000Z",
  "media": [{"id": "9b1c…", "type": "image", "filename": "loaf.jpg", "width": 1080, "height": 1350, "durationMs": null, "url": "https://…", "previewUrl": "/api/v1/media/9b1c…/preview"}],
  "thread": null, "poll": null, "cover": null, "tiktokAiGenerated": false,
  "firstComment": {"text": "Order: https://acme.example", "status": "posted"},
  "targets": [{"accountId": "2ae8…", "platform": "instagram", "username": "acmebakery", "avatarUrl": "https://…", "status": "published", "url": "https://instagram.com/p/…", "error": null}],
  "pollUrl": null, "next": null
}}
```

| Field | Notes |
|---|---|
| `status` | `needs_approval`, `scheduled`, `publishing`, `published`, `partial`, `failed`, `rejected`, `cancelled` |
| `settled` | `true` when nothing more will change. Until then poll `pollUrl` every few seconds |
| `targets[]` | One per account, each with its own `status`, live `url` and `error` |
| `firstComment.status` | `pending`, `posted` or `failed` |
| `next` | Plain-language next step, for example who must approve |

## Errors

`404 post_not_found` if the id isn't in this workspace.

## Common questions

### How do I know when a post is done?

Poll GET /posts/{id} until settled is true. Each target then shows published with a url, or failed with an error.

### Can I list more than 100 posts?

Not yet. The list returns the newest 100 at most.

### Why does a post say partial?

Some targets published and others failed. Check targets[].error.