Scheduling

How Scheduling Works

Scheduling works identically for all 14 supported platforms (X, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, Telegram, Reddit, Pinterest, TikTok, YouTube, Google Business Profile, and Snapchat). When you include schedule_at in a create post or thread request, Chirpie stores it with status scheduled and publishes it to the target platform at the specified time.

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "text": "This posts at noon UTC tomorrow",
    "schedule_at": "2026-03-24T12:00:00Z"
  }'

Timing

• schedule_at must be a future ISO 8601 datetime
• The scheduler runs every minute — posts publish within ~60 seconds of their scheduled time
• All times are UTC

Post Status Flow

scheduled → publishing → published
                      → failed (retry up to 3 times)

Thread Scheduling

When scheduling a thread, all posts share the same schedule_at. The thread publishes atomically — if any post fails, the entire thread is rescheduled for retry.

curl -X POST https://chirpie.ai/api/v1/threads \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "posts": [
      { "text": "Thread post 1" },
      { "text": "Thread post 2" }
    ],
    "schedule_at": "2026-03-24T12:00:00Z"
  }'

Scheduled Post Limits

Scheduled posts count against a separate monthly quota:

Canceling a Scheduled Post

Delete the post before its scheduled time to cancel it:

curl -X DELETE https://chirpie.ai/api/v1/posts/POST_ID \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY"

Minimum Spacing

Scheduled posts for the same account must be at least 5 minutes apart. If you try to schedule a post within 5 minutes of an existing scheduled post for the same account, the API returns 400:

{ "error": { "code": "bad_request", "message": "Scheduled posts must be at least 5 minutes apart for the same account." } }

This prevents platform API rate limit issues and ensures reliable delivery.

Retry Behavior

Failed posts are retried up to 3 times with a 5-minute delay between attempts. After 3 failures, the post is marked as failed with an error_message describing the issue.