Publish or schedule a thread
chirpie_threadCreate a thread (multiple posts) on X/Twitter, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, or Telegram. Publish to several accounts at once by naming account_ids instead of account_id, and give one of them a thread of its own with account_configurations. X, Bluesky, Threads, Mastodon, and Telegram support native reply threading. Others degrade gracefully to standalone posts. A THREAD IS ATOMIC: if any part fails, every part already published is deleted from the platform and the whole thread's quota is refunded, and the error's thread_rollback says what was rolled back. Two codes tell you whether a retry is safe: upstream_error means nothing of the thread is on the platform, so repeating the request is safe, while thread_rollback_incomplete means the posts named in thread_rollback.still_live are still up with their ids and URLs, and repeating the request would publish them twice. On an Instagram account connected by signing in with Instagram, where Chirpie cannot delete a published post, a failed thread always reports its published parts as still live. On X, each post in the thread whose text contains a link is billed at $0.25 on paid plans; on the Free plan such threads are rejected (x_link_posts_require_paid_plan). X accounts connected with your own X API keys are exempt. A thread that would cross the monthly post or scheduled-post quota answers 429 usage_limit_exceeded and publishes nothing; the per-minute burst limit on the API key answers 429 rate_limited. Set draft: true to save the thread without sending it: nothing reaches the platform, nothing counts against the quota, a draft thread may still be a single part long, and the answer carries a warnings array. chirpie_update_post on any of its parts promotes it, and the whole thread goes together.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| draft | No | Save the thread without sending it. Every part is stored with status draft, nothing reaches the platform, and it costs no quota. | |
| posts | Yes | Array of posts in the thread. A thread needs at least 2 to publish; a draft may be saved with 1 while it is still being written. | |
| timezone | No | The IANA timezone a schedule_at with no offset is read in, such as 'America/New_York'. Daylight saving is worked out for the date named, which is what makes '09:30 on 1 November' come out right. Ignored when schedule_at already carries an offset. Leave it out to use the timezone saved on the account. | |
| account_id | No | Account ID to post from (X, Bluesky, LinkedIn, Threads, Mastodon, Instagram, Facebook, or Telegram). Some platforms degrade to standalone posts. Use this or account_ids, not both. | |
| account_ids | No | Account IDs to publish the same thread to, 1 to 25 of them, each named once. Naming this instead of account_id answers with a group_id and one result per account, in the order given, each with its own `success`: an account whose platform refused is reported there while the others stay published. | |
| schedule_at | No | ISO 8601 datetime to schedule the thread. Either an absolute instant carrying a timezone, such as '2026-04-01T14:00:00Z' or '2026-04-01T16:00:00+02:00', or a local time with no offset, such as '2026-11-01T09:30:00', which is read in the timezone parameter or the one saved on the account and is refused when there is neither. Scheduled threads publish within ~5 minutes of this time. On a draft it is only the time you have in mind. | |
| configuration | No | Per-platform publishing options, keyed by platform. Instagram takes a feed post, a story or a reel, and a Facebook Page takes a feed post or a story; leave it out and everything publishes to the feed. Nothing is dropped quietly: a block keyed on a platform that takes no options, on a platform no account in the call uses, or a field the chosen placement does not carry, is refused with 400 configuration_unsupported naming the platform and the field. One block serves every account of that platform; give one account its own with an account_configurations entry. A thread publishes to the feed: an Instagram story or reel, and a Facebook Page story, are each a single post, so a thread asking for one of those placements is refused. | |
| first_comment | No | A comment to publish under the thread's LAST post once the thread is out. One comment for the whole thread, not one per part, and reported on that last part's first_comment. Available on X, Threads, Instagram and Facebook only: anywhere else is refused with 400 first_comment_unsupported rather than dropped. It counts as one post against the monthly quota, and it never fails the thread. | |
| idempotency_key | No | A key of your own making that makes retrying this call safe. The same key with the same request replays the first answer for 24 hours instead of sending it again; the same key with a different request is refused with 422 idempotency_key_reused, and a retry that arrives while the first is still running is refused with 409 idempotency_in_progress; a retry after the first has finished collects the replay. | |
| account_configurations | No | Per-account threads, keyed by account ID. Every key must also be in account_ids. An account with no entry publishes the shared posts. |