Every post flows through the same five-stage pipeline, regardless of whether you're using the SDK, CLI, MCP, or REST API.

The states

pending → processing → publishing → completed
                                  ↘ partial_failure
                                  ↘ failed

Plus two start states:

• draft — created with saveDraft: true, waiting for publishDraft()
• scheduled — created with scheduledAt, waiting for the scheduled time

What each state means

Status	What's happening
pending	Queued; about to be picked up
processing	Media being transcoded / validated
publishing	Fanning out to each connected platform in parallel
completed	Every channel succeeded
partial_failure	Some channels succeeded, some failed
failed	All channels failed
draft	Saved, not yet published
scheduled	Will publish at scheduledAt

The fan-out

A single post with N connections produces N channels — one per connection. Each channel publishes independently:

const status = await socifyr.uploads.getStatus(uploadId)
//  {
//    status: 'partial_failure',
//    channels: [
//      { platform: 'instagram',
//        result: { status: 'success', postUrl: 'https://instagram.com/p/...' } },
//      { platform: 'x',
//        result: { status: 'failed', error: 'rate limit exceeded' } },
//    ]
//  }

If one channel fails, the others are unaffected.

Retrying

uploads.retry(id) re-queues only the failed channels:

await socifyr.uploads.retry(uploadId)

Successful channels are skipped via an idempotency guard — you can't double-post.

Polling vs webhooks

Approach	When to use
Polling (getStatus / --wait)	Scripts, CLI users, one-off jobs
Webhooks	Production apps — get a push when state changes

See Webhooks for the full setup.

Timing

Typical times from publishing to completed:

Content	Time per channel
Text	< 2 sec
1–3 images	3–10 sec
Carousel (10 images)	15–30 sec
Short video (< 60s)	30–90 sec
Long video (10+ min)	2–10 min

YouTube and TikTok video processing on the platform side can add several more minutes — the result.publishedAt reflects platform-side completion, not just upload.