Scheduled posts

/api/v1/scheduled-posts is two endpoints. GET lists the user's queue. POST inserts a new row that will fire when its scheduled_for elapses. The same cron worker that drains the in-app composer's queue picks up rows written through this endpoint, so an integration can offload "schedule for later" to Post-EZ without re-implementing the publish dispatcher.

List queue

curl -X GET 'https://postez.app/api/v1/scheduled-posts?limit=20&status=scheduled' \
  -H "Authorization: Bearer pz_YOUR_KEY_HERE"

Required scope: scheduled.read. Rate limit: 600 requests per minute per key.

Query parameters

• limit (number, optional) — max rows to return. Default 50, max 200.
• status (string, optional) — comma-separated list of statuses to filter on, e.g. scheduled,publishing,failed.

Response

{
  "ok": true,
  "posts": [
    {
      "id": "9d4a...",
      "caption": "Launch announcement",
      "media_urls": ["https://..."],
      "platforms": ["instagram", "x"],
      "scheduled_for": "2026-06-01T15:00:00.000Z",
      "status": "scheduled",
      "fail_reason": null,
      "retry_count": 0,
      "created_at": "2026-05-22T18:01:09.000Z",
      "updated_at": "2026-05-22T18:01:09.000Z"
    }
  ]
}