Scheduled posts

Scheduled posts let you queue content now to deliver later. The platform handles the wait, the retry on the target network, and the delivery confirmation.

Submitting

{
  "platform": "twitter",
  "accountId": "acc_...",
  "status": "scheduled",
  "scheduledAt": "2026-04-20T14:00:00Z",
  "postType": "tweet",
  "content": "Launch day."
}

Rules:

scheduledAt must be ISO 8601 with timezone (Z or +00:00). No bare local times.
Must be in the future. A scheduledAt in the past returns 400.
No hard upper bound, but scheduling a post more than 1 year out will log a warning; platform terms may have changed by then.

Time zones

Always store and submit in UTC. Display in the user's local zone in the UI. Never rely on the server's local time; Postato's workers run in UTC regardless.

If your user says "3 PM Monday in São Paulo," convert to UTC on the client side (subtract the offset) before calling the API. Libraries like date-fns-tz or luxon handle this.

Lifecycle

POST /posts (status: scheduled)
  → status: "scheduled"  (waiting)
  → status: "queued"     (at scheduledAt, worker picks it up)
  → status: "publishing" (calling the platform)
  → status: "published"  (delivery confirmed)
         or status: "failed" (terminal error)

Editing a scheduled post

Use PATCH /posts/{id} or the MCP update_post tool. Fields editable:

content, media: replace the payload
scheduledAt: reschedule to a new time
status: promote to publish (fire now) or drop back to draft

Editing cancels the outstanding job and re-enqueues. If you want to guarantee no double-publish when editing close to fire time, pass a fresh idempotencyKey.

Either PATCH it back to draft, or DELETE the post entirely. Both are safe up until status: "publishing". After that, the platform delivery is in flight and cannot be aborted from Postato's side.

Reliability

The scheduler runs every few seconds; scheduledAt is accurate to within ~10 seconds.
If the platform is down at fire time, Postato retries for ~15 minutes with backoff before marking the post failed.
If Postato itself has an outage at fire time, catch-up logic processes missed jobs within ~1 minute of recovery.

Bulk scheduling

For many posts at once, loop individual POST /posts calls with a stable Idempotency-Key per post and stagger scheduledAt across minutes. See the Staggered publishing recipe for a production pattern.

Avoid scheduling dozens of posts for the exact same scheduledAt; you'll trip platform rate limits at fire time. Stagger across minutes.

Approvals + scheduling

If the workspace requires approval, the post enters pending_approval first. See Approvals for how scheduledAt interacts with approval timing.

Scheduled Posts