# List Social Posts

> List the social posts in your workspace, newest first

- **URL**: https://orshot.com/docs/api-reference/social-posts-list

---

## Overview

Returns the social posts in your workspace — drafts waiting for review, scheduled posts, and everything already published or failed. This is the same history the **Posts Log** shows in your dashboard.

Use it to find a post's `id` before reading, editing, publishing or discarding it.

```markdown tab="Endpoint"
https://api.orshot.com/v1/social/posts
```

## Request

**Request**
```js
await fetch("https://api.orshot.com/v1/social/posts?status=draft&limit=10", {
  method: "GET",
  headers: {
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
});
```

**Response**
```json
{
  "data": [
    {
      "id": 512,
      "status": "draft",
      "content": "Our new pricing is live.",
      "media_urls": ["https://storage.orshot.com/.../launch.png"],
      "platforms": ["linkedin", "twitter"],
      "accounts": [
        {
          "account_id": 15,
          "platform": "linkedin",
          "username": "acme-inc",
          "name": "Acme Inc",
          "status": "draft"
        },
        {
          "account_id": 22,
          "platform": "twitter",
          "username": "acmehq",
          "name": "Acme",
          "status": "draft"
        }
      ],
      "is_editable": true,
      "scheduled_for": null,
      "published_at": null,
      "created_at": "2026-08-11T17:24:09.752914+00:00",
      "render_id": 889021
    }
  ],
  "pagination": {
    "limit": 10,
    "has_more": false,
    "next_cursor": null
  }
}
```

## Query Parameters

| Parameter    | Type    | Required | Description                                                                                  |
| ------------ | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `status`     | String  | No       | Only posts in this state: `draft`, `scheduled`, `published`, `processing`, `partial`, `failed` |
| `platform`   | String  | No       | Only posts targeting this platform, e.g. `linkedin`                                            |
| `account_id` | Integer | No       | Only posts targeting this connected account                                                    |
| `limit`      | Integer | No       | Posts per page, 1–50 (default 25)                                                              |
| `cursor`     | Integer | No       | `next_cursor` from a previous response, to fetch the next older page                           |

Pass `status=draft` to list exactly the posts that are being held and have not reached any platform.

## Post Object

Every endpoint that returns a post returns this shape.

| Field                        | Type    | Description                                                                                       |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `id`                         | Integer | Post ID. Use it with the other post endpoints                                                        |
| `status`                     | String  | `draft`, `scheduled`, `published`, `processing`, `partial` or `failed`                               |
| `content`                    | String  | The caption                                                                                          |
| `media_urls`                 | Array   | Media attached to the post                                                                           |
| `platforms`                  | Array   | Platform names this post targets                                                                     |
| `accounts`                   | Array   | Per-account results — the detailed view of `platforms`                                               |
| `accounts[].account_id`      | Integer | The exact connected account. `null` on posts created before per-account results existed              |
| `accounts[].status`          | String  | This account's own outcome                                                                           |
| `accounts[].url`             | String  | Link to the live post, once published                                                                |
| `accounts[].error`           | String  | Why this account failed, when it did                                                                 |
| `is_editable`                | Boolean | Whether Orshot is still holding this post, i.e. whether it can be edited or published                |
| `is_discardable`             | Boolean | Whether it can be deleted — true unless at least one account already went live                       |
| `scheduled_for`              | String  | When it will publish, if scheduled                                                                   |
| `published_at`               | String  | When it published                                                                                    |
| `created_at`                 | String  | When it was created                                                                                  |
| `render_id`                  | Integer | The render this post came from, when it was created by rendering a template                          |

Branch on the two capability flags rather than on `status` — they are not the same test:

- `is_editable` is `true` only while the post is held (`draft` or `scheduled`). Editing and publishing require it.
- `is_discardable` is `true` unless at least one account already published. A `failed` post is discardable but not editable; a `partial` post is neither.

## Error Responses

### Invalid cursor (400)

```json
{
  "error": "Invalid cursor",
  "message": "cursor must be a post id"
}
```

### Unauthorized (403)

```json
{
  "error": "Access Forbidden"
}
```

## Rate Limits

- 20 requests per minute per workspace, shared across all social endpoints