# List posts

> List posts with the Wavegrain Posting API: GET /api/v1/posts. Parameters, responses and an example request.

> Index of these docs: https://wavegrain.com/developers/llms.txt

`GET /api/v1/posts` is part of the [Posting API](/developers/posting-api). Every call needs an access key: see [Authentication](/developers/authentication).

Needs the `read` permission.

Posts with a delivery due in the window, newest first. The window defaults to the last and the next 30 days and may be at most 100 days.

## Parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `from` | query | string | no | Start of the window, ISO 8601 with an offset. |
| `to` | query | string | no | End of the window (not included), ISO 8601 with an offset. |
| `status` | query | "queued" \| "preparing" \| "sending" \| "processing" \| "action_required" \| "outcome_unknown" \| "published" \| "failed" \| "cancelled" \| "awaiting_confirmation" | no | Only posts with a delivery in this state, or `awaiting_confirmation` for posts made through the API that wait for the owner's confirm. |
| `limit` | query | integer | no | Posts per page, 1 to 100. |
| `cursor` | query | string | no | The `nextCursor` of the page before. |

## Example request

```bash
curl https://wavegrain.com/api/v1/posts \
  -H "Authorization: Bearer $WAVEGRAIN_KEY"
```

## Responses

| Status | Meaning |
| --- | --- |
| 200 | A page of posts. |
| 400 | A query parameter is not valid, or the window is too wide. |
| 401 | No access key, or an unknown, revoked or expired one |
| 403 | The key lacks the permission, or the account has no active plan |
| 429 | Too many requests for the key or the account |
| 500 | Something went wrong on Wavegrain's side; try again, and send the request id if it keeps failing. |

A successful answer:

```json
{
  "posts": [
    {
      "id": "post_V1StGXR8_Z5jdHi6B",
      "source": "api",
      "slideshowId": null,
      "title": null,
      "status": "confirmed",
      "confirmUrl": null,
      "scheduledFor": "2026-11-07T09:00:00.000Z",
      "targets": [
        {
          "accountId": "acc_4Ft7Wz",
          "accountName": "Koi Kitchen",
          "network": "instagram",
          "state": "delivered",
          "deliveryId": "dlv_9xQ2Kp",
          "reason": null
        }
      ],
      "deliveries": [
        {
          "id": "dlv_9xQ2Kp",
          "accountId": "acc_4Ft7Wz",
          "accountName": "Koi Kitchen",
          "network": "instagram",
          "status": "published",
          "label": "Published on Instagram",
          "reason": null,
          "errorCode": null,
          "scheduledFor": "2026-11-07T09:00:00.000Z",
          "automatic": false,
          "canCancel": false,
          "link": "https://www.instagram.com/p/C9xYz/"
        }
      ]
    }
  ],
  "nextCursor": null
}
```

## More in the Posting API

- [List brands, groups and connected accounts](/developers/api/list-accounts): `GET /api/v1/accounts`
- [Create a post](/developers/api/create-post): `POST /api/v1/posts`
- [Get a post](/developers/api/get-post): `GET /api/v1/posts/{id}`
- [Cancel a post](/developers/api/cancel-post): `DELETE /api/v1/posts/{id}`
- [Start an image or video upload](/developers/api/create-upload): `POST /api/v1/media`
- [Get an upload](/developers/api/get-upload): `GET /api/v1/media/{id}`
- [Delete a video](/developers/api/delete-video): `DELETE /api/v1/media/{id}`
- [Finish and check a video upload](/developers/api/complete-video-upload): `POST /api/v1/media/{id}/complete`
- [Write captions](/developers/api/write-captions): `POST /api/v1/captions`
- [All endpoints](/developers/api)
