Publishing guide
What actually happens between hitting publish and a post appearing on a network — composing, scheduling, fan-out, statuses, and how failures are reported.
How a post travels
One post can target a dozen networks, but nothing is published “to all of them” as a single act. Delivery is per-network from the moment you press publish, and every step below is observable — in the app and through the API.
- 1
Connect an account
Each network is connected once through its own OAuth flow and then holds a seat. Tokens are refreshed in the background; a network that revokes one marks the account for reconnection rather than failing silently at publish time. - 2
Compose
Pick the networks, then the post type —post,reel,storyor a long-formvideo. Media rules and caption caps tighten to the strictest selected network, so a caption that fits everywhere is the one you can send everywhere. Per-network captions and options override the shared ones. - 3
Schedule, or publish now
A scheduled post waits in its own timezone-aware slot and is picked up by the dispatcher. “Publish now” skips the wait but takes the same path — same validation, same per-network delivery. - 4
Fan out
At publish time a multi-network post splits into one row per network. Each is delivered and reported independently, which is why one network failing never blocks the others. - 5
Read the result
Every attempt writes a per-network result: the remote post id and permalink on success, a categorised error on failure. The API exposes the same object asplatform_results.
Composing
The composer narrows to what your selected networks share. Pick Instagram and X together and the caption counter drops to 280 — X’s limit, the first wall you’d hit. Give X its own caption and the others get their full length back.
Media works the same way: the item count drops to the smallest one, and a media type nobody accepts disappears. Aspect ratio is the exception — we recommend, never block. See Media requirements for the shapes that actually work.
Post statuses
A post carries one status; each network attached to it carries its own result.
| Status | Meaning |
|---|---|
draft | Saved, never sent. Editable indefinitely. |
scheduled | Waiting for its slot. The dispatcher picks it up when due. |
queued | Claimed for delivery right now — a transient state, seconds long. |
published | Every selected network accepted it. |
partial_published | At least one network accepted it and at least one refused. |
failed | No network accepted it. The per-network error explains why. |
partial_published is the honest one. A post that reached four networks out of five is not a success and not a failure, and flattening it either way would hide the one that needs your attention.
When a network refuses
Every provider error becomes a plain message, with the original code kept underneath for support. A bad aspect ratio, an expired token and a too-long caption each read differently, because each has a different fix.
Temporary problems — a network briefly down, a video still processing — are retried for you. Permanent ones aren’t. A 3.4:1 image will fail on Instagram every single time, so you hear about it immediately instead of after five quiet retries.
Next steps
Per-network capabilities live in Networks & limits, file rules in Media requirements, and account/post allowances in Plans & quotas. To drive all of this from code, start at the Quickstart.