# List posts

Return your project's most recent posts, newest first, with their per-platform targets.


```http
GET https://social-publish-api.onrender.com/v1/posts
```

Returns the most recently created posts in the API key's project, newest first, each with its targets. Posts created from the dashboard Playground are included.

## Headers

| Header | Required | Description |
| --- | --- | --- |
| `x-access-key` | Yes* | Your API key. *Or send `Authorization: Bearer <key>`. |

## Query parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | integer | `20` | Number of posts to return, from 1 to 100. Larger values are capped at 100 and negative values return 1; a missing, `0` or non-numeric value uses 20. |

There is no cursor or offset, and no status filter. To browse older posts or filter by status, use **[Posts](https://social-publish-kappa.vercel.app/dashboard/posts)** in the dashboard, or keep the post IDs returned by [Create a post](/docs/api/create-post) and fetch them with [Get a post](/docs/api/get-post).

## Request

```bash tab="cURL"
curl "https://social-publish-api.onrender.com/v1/posts?limit=5" \
  -H "x-access-key: $RELAYCAST_API_KEY"
```

```ts tab="Node.js"
const res = await fetch("https://social-publish-api.onrender.com/v1/posts?limit=5", {
  headers: { "x-access-key": process.env.RELAYCAST_API_KEY! },
});
const { data: posts } = await res.json();
const failed = posts.filter((p: { status: string }) => p.status === "failed" || p.status === "partial");
```

```python tab="Python"
import os, requests

res = requests.get(
    "https://social-publish-api.onrender.com/v1/posts",
    params={"limit": 5},
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
)
posts = res.json()["data"]
failed = [p for p in posts if p["status"] in ("failed", "partial")]
```

## Response

An array of posts with the same shape as [Get a post](/docs/api/get-post#post-fields).

```json title="Response 200"
{
  "data": [
    {
      "id": "a3f8c2d1-9b7e-4c6a-8f5d-2e1b0c9a8d7f",
      "content": "Our new release is live. Faster uploads, a calendar view and more.",
      "media": [{ "url": "https://cdn.example.com/release.jpg", "type": "image", "altText": "Release banner" }],
      "status": "partial",
      "scheduledFor": "2026-11-02T15:00:00.000Z",
      "request": {
        "content": "Our new release is live. Faster uploads, a calendar view and more.",
        "targets": [
          { "accountId": "6f1c2a7e-4b8d-4f7a-9a51-2d3c4b5a6e7f" },
          { "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29" }
        ],
        "media": [{ "url": "https://cdn.example.com/release.jpg", "type": "image", "altText": "Release banner" }],
        "publishNow": false,
        "scheduledFor": "2026-11-02T15:00:00Z"
      },
      "createdAt": "2026-10-05T09:30:12.441Z",
      "updatedAt": "2026-11-02T15:00:41.093Z",
      "targets": [
        {
          "id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
          "accountId": "6f1c2a7e-4b8d-4f7a-9a51-2d3c4b5a6e7f",
          "platform": "twitter",
          "status": "published",
          "content": null,
          "options": {},
          "attempts": 1,
          "externalPostId": "1852700000000000000",
          "externalUrl": "https://x.com/acme/status/1852700000000000000",
          "errorCode": null,
          "errorMessage": null,
          "publishedAt": "2026-11-02T15:00:06.218Z",
          "createdAt": "2026-10-05T09:30:12.441Z",
          "updatedAt": "2026-11-02T15:00:06.218Z"
        },
        {
          "id": "c9b8a7f6-e5d4-4c3b-a291-807f6e5d4c3b",
          "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29",
          "platform": "instagram",
          "status": "failed",
          "content": null,
          "options": {},
          "attempts": 1,
          "externalPostId": null,
          "externalUrl": null,
          "errorCode": "media_error",
          "errorMessage": "Instagram could not process the media: ERROR",
          "publishedAt": null,
          "createdAt": "2026-10-05T09:30:12.441Z",
          "updatedAt": "2026-11-02T15:00:41.093Z"
        }
      ]
    }
  ]
}
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthorized` | Missing or invalid API key. |
| 429 | `rate_limited` | Rate limit exceeded for this key. |