Scheduled Posts

Scheduled Posts use scheduled_at and the worker-backed queue. Use this flow when content should publish later, or when you need an end-to-end test of API, queue, worker, and post status updates.

Create A Scheduled Post

postmcp post schedule \
  --text "Launch note" \
  --to bluesky:acct_123 \
  --schedule 2026-05-15T14:00:00.000Z \
  --idempotency-key idem_schedule_123 \
  --json

The API form uses scheduled_at:

{
  "workspace_id": "wrk_123",
  "created_by_type": "agent",
  "created_by_id": "scheduler",
  "text": "Launch note",
  "scheduled_at": "2026-05-15T14:00:00.000Z",
  "targets": [{ "platform": "bluesky", "connected_account_id": "acct_123" }]
}

Use an idempotency-key header for retries so duplicate scheduler calls do not create duplicate post groups.

Sandbox Scheduling

Set sandbox for end-to-end testing without live platform posts:

postmcp post schedule \
  --text "Worker smoke test" \
  --to bluesky:acct_sandbox \
  --schedule 2026-05-15T14:00:00.000Z \
  --sandbox \
  --json

Sandbox scheduling exercises validation, persistence, queueing, publish execution, webhook delivery, usage accounting, and dashboard status updates.

Status And Lifecycle

Inspect a scheduled post by its post group ID:

postmcp post status --post-group-id pg_123 --json

Status values include scheduled, publishing, published, failed, and cancelled. Subscribe to lifecycle webhooks with webhook_url to receive post.scheduled, post.published, and post.failed events as they happen. See Webhooks for delivery details.

If a scheduled post is late or stuck, capture the post group ID, target account, and trace_id, then see Troubleshooting.