# List posts

> List the posts in a workspace, newest first.

**Source:** https://postprism.app/docs/api/list-posts  
**Updated:** 2026-10-10

---

`GET https://studio.postprism.app/api/v1/posts`

Returns posts in the workspace, most recently created first. Filter by status and page through the results with `limit` and `offset`.

## Parameters

| Name | In | Type | Description |
| --- | --- | --- | --- |
| `status` | query | string | Only return posts with this status. One of: `draft`, `scheduled`, `publishing`, `published`, `failed`. |
| `limit` | query | integer | How many posts to return. Default 50, maximum 100. |
| `offset` | query | integer | How many posts to skip. Default 0. |
| `workspace_id` | query | uuid | Act on another workspace you belong to. Defaults to the workspace your API key was created in. |

## Example

```bash
curl "https://studio.postprism.app/api/v1/posts?status=scheduled&limit=20" \
  -H "Authorization: Bearer pp_live_your_api_key"
```

## Response

Status `200`.

`data` is an array of `PostSummary`: A post as returned by `GET /api/v1/posts`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | uuid | The post ID. |
| `base_content` | string | The shared draft the per-platform versions start from. |
| `platforms` | string[] | Platform keys the post targets. |
| `platform_content` | object | Per-platform versions, keyed by platform key. |
| `status` | string | Where the post is in its lifecycle. One of: `draft`, `scheduled`, `publishing`, `published`, `failed`. |
| `scheduled_at` | date-time, nullable | When the post publishes, in UTC. `null` for drafts. |
| `published_at` | date-time, nullable | When the post was published, or `null`. |
| `media` | object[] | Attached images and videos. |
| `ai_generated` | boolean | Whether the post was written with Postprism AI. |
| `created_at` | date-time | When the post was created. |

```json
{
  "data": [
    {
      "id": "3f1c2a9e-0000-4000-8000-00000000a001",
      "base_content": "Our autumn menu is here: maple oat latte, pumpkin cold brew and a new almond croissant.",
      "platforms": ["linkedin", "twitter"],
      "platform_content": {
        "linkedin": {
          "content": "Our autumn menu is here. Three new drinks, one new pastry, all made in-house at Juniper Roasters. Which one are you trying first?"
        },
        "twitter": {
          "content": "Autumn menu, now pouring. Maple oat latte first?",
          "hashtags": ["#autumnmenu", "#coffeeshop"]
        }
      },
      "status": "scheduled",
      "scheduled_at": "2026-10-16T09:30:00Z",
      "published_at": null,
      "media": [
        {
          "url": "https://…/launch-photo.webp",
          "type": "image"
        }
      ],
      "ai_generated": false,
      "created_at": "2026-10-10T14:02:11Z"
    }
  ],
  "error": null
}
```

## Errors

| Status | Message | When |
| --- | --- | --- |
| 401 | `Invalid or revoked API key` | The `Authorization` header is missing, malformed, or the key was revoked. |
| 429 | `Too many requests` | You went over the hourly limit. See Rate limits. |
| 404 | `Workspace not found, or you are not a member of it.` | The `workspace_id` you passed (or your key’s default workspace) is not one you belong to. |