Post Lifecycle

When you create a post through Postproxy, it moves through a predictable lifecycle. This guide explains each state, what to expect, and how to handle different scenarios.

Lifecycle overview

Draft

publish / schedule

Pendingmedia processing

media ok

Scheduled

at scheduled time

Processing< 1 sec

jobs initiated

Processed

media failed

Media Processing Failed

Three layers of status

Every post has three independent status layers. Understanding these is essential for building reliable integrations.

Post status

Overall state of the post: draft, pending, scheduled, processing, processed, or media_processing_failed

Platform status

Individual status for each social platform: pending, processing, published, failed, or failed_waiting_for_retry

Media status

Processing state of each attachment: pending, processed, or failed

Post states

Draft Draft

Your post is saved but not scheduled for publication. It’s a work in progress.

{
  "status": "draft",
  "draft": true,
  "scheduled_at": null
}

Next step: Call POST /api/posts/:id/publish to publish immediately, or update the post with scheduled_at to schedule it.

Can edit/delete: Yes

Pending Pending

Your post has been created and media is being processed. The post is not yet ready for publication.

{
  "status": "pending",
  "draft": false,
  "media": [
    { "status": "pending", "content_type": "image/jpeg" }
  ]
}

What happens:

Media files are downloaded from URLs or processed from uploads
Files are validated and prepared for each platform
Media status transitions: pending → processed or failed

Next step:

All media processed successfully → status becomes scheduled
Any media failed → status becomes media_processing_failed

Typical duration: Images 1–15 seconds. Videos 10–120 seconds depending on size.

Can edit/delete: Cannot edit. Can delete.

Scheduled Scheduled

Your post is ready and queued for publication at the specified time. All media has been successfully processed.

{
  "status": "scheduled",
  "draft": false,
  "scheduled_at": "2024-01-15T10:00:00Z",
  "media": [
    { "status": "processed", "url": "https://cdn.postproxy.dev/..." }
  ]
}

Next step: At the scheduled time, the system changes status to processing, initiates publishing jobs, and immediately transitions to processed.

Can edit/delete: Cannot edit. Can delete.

Processing Processing

A brief intermediate state while platform publishing jobs are being enqueued.

{
  "status": "processing",
  "draft": false
}

Duration: Usually less than 1 second.

Can edit/delete: No

Processed Processed

Platform publishing jobs have been initiated. The post is now in the hands of each platform’s publishing system.

{
  "status": "processed",
  "draft": false
}

At the platform level, you may see various states:

{
  "platforms": [
    { "network": "twitter", "status": "published" },
    { "network": "instagram", "status": "processing" },
    { "network": "youtube", "status": "failed" }
  ]
}

Can edit/delete: Cannot edit. Can delete from Postproxy (does not remove from social platforms).

Media Processing Failed Media Processing Failed

One or more media attachments failed to download or process. This is the only failure state at the post level.

{
  "status": "media_processing_failed",
  "media": [
    {
      "id": "abc123",
      "status": "failed",
      "error_message": "Media file not found (404)",
      "source_url": "https://example.com/missing.jpg"
    }
  ]
}

Recovery: Create a new post with correct media URLs and delete the failed post.

Platform-level states

Even if a post has status: "processed", individual platforms can succeed or fail independently.

Platform status flow

pending→processing→published

↘failed→failed_waiting_for_retry→processing(retry)

Status definitions

Status	Meaning
`pending`	Waiting to be processed
`processing`	Currently publishing — active API call in progress
`published`	Successfully live on the social network
`failed`	Permanent failure — check `error_message`
`failed_waiting_for_retry`	Temporary failure, retry scheduled — see `retry_after`

Partial success example

Post to 3 platforms where 2 succeed and 1 fails:

{
  "status": "processed",
  "platforms": [
    { "network": "twitter", "status": "published" },
    { "network": "linkedin", "status": "published" },
    {
      "network": "instagram",
      "status": "failed",
      "error_message": "Instagram account disconnected"
    }
  ]
}

Retry behavior

Postproxy automatically retries transient failures so you don’t have to.

Retried automatically

Network timeouts, temporary rate limits, platform API temporarily unavailable, quota errors

Not retried

Invalid credentials, account disconnected, content policy violations, invalid media format

Retry schedule

Retries use exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	15 minutes
4th retry	30 minutes
5th retry	60 minutes

Maximum: 5 retry attempts

During a retry

{
  "network": "twitter",
  "status": "failed_waiting_for_retry",
  "error_message": "Rate limit exceeded",
  "retry_attempts": 2,
  "retry_after": "2024-01-15T10:20:00Z"
}

Media processing

When you include media in a post, it must be processed before publishing can begin.

Media states

Status	Meaning	Duration
`pending`	Downloading/processing	1–30 seconds
`processed`	Ready for publication	—
`failed`	Could not process	Check `error_message`

Processing timeline

Media type	Typical duration
Small image (< 1 MB)	1–5 seconds
Large image (1–10 MB)	5–15 seconds
Short video (< 100 MB)	10–30 seconds
Large video (> 100 MB)	30–120 seconds

Common media errors

Error	Cause
`Media file not found (404)`	URL doesn’t exist
`Access denied to media file (403)`	URL requires authentication
`Connection timed out`	Server too slow or unreachable
`Unsupported format`	File type not supported by platform

Webhook events

Subscribe to webhooks to receive real-time updates about your posts. See Webhooks for setup.

Event	When it fires
`post.processed`	Post finished processing, jobs initiated
`platform_post.published`	Individual platform published successfully
`platform_post.failed`	Individual platform failed
`platform_post.failed_waiting_for_retry`	Retry scheduled for a platform
`media.failed`	Media processing error
`platform_post.insights`	New analytics available

Example: post.processed

{
  "event_type": "post.processed",
  "data": {
    "id": "abc123",
    "body": "Hello world!",
    "status": "processed",
    "platforms": [
      { "platform": "twitter", "status": "published" },
      { "platform": "instagram", "status": "published" }
    ]
  }
}

Example: platform_post.failed

{
  "event_type": "platform_post.failed",
  "data": {
    "id": "pp_456",
    "post_id": "abc123",
    "platform": "instagram",
    "status": "failed",
    "error": "Invalid credentials"
  }
}

Common scenarios

Scenario 1: Scheduled post (text only)

POST /api/posts
{
  "post": {
    "body": "Big announcement tomorrow!",
    "scheduled_at": "2024-01-16T09:00:00Z"
  },
  "profiles": ["twitter", "linkedin"]
}

Immediate response: status: "scheduled" (no media to process)
At scheduled time: processing → processed (jobs enqueued, < 1 second)
Platform jobs run asynchronously — Twitter and LinkedIn publish independently

Scenario 2: Scheduled post (with media)

POST /api/posts
{
  "post": {
    "body": "Big announcement tomorrow!",
    "scheduled_at": "2024-01-16T09:00:00Z"
  },
  "profiles": ["instagram", "facebook"],
  "media": ["https://example.com/photo.jpg"]
}

Immediate response: status: "pending", media status: "pending"
Media processing: 5–15 seconds
Media processed → post becomes scheduled
At scheduled time: processing → processed (jobs initiated)
Platform jobs run asynchronously

Scenario 3: Immediate publish

POST /api/posts
{
  "post": { "body": "Live now!" },
  "profiles": ["twitter"]
}

System sets scheduled_at to current time
Status: scheduled → processing → processed (< 1 second)
Twitter platform job runs (1–5 seconds)

Total time: 2–10 seconds

Scenario 4: Draft workflow

# Step 1: Create draft
POST /api/posts
{
  "post": { "body": "Work in progress", "draft": true },
  "profiles": ["twitter"]
}
# Response: status: "draft"

# Step 2: Publish when ready (hours or days later)
POST /api/posts/abc123/publish
# Response: status: "processing"

The draft stays in draft status with no automatic publishing until you explicitly call /publish.

Scenario 5: Partial platform failure

Post status: processing → processed (< 1 second)
Platform jobs run independently:
- Twitter: published (2 sec)
- LinkedIn: published (3 sec)
- Instagram: failed — account disconnected (4 sec)
Post remains processed — platform statuses show mixed results

After platforms finish:

{
  "status": "processed",
  "platforms": [
    { "network": "twitter", "status": "published" },
    { "network": "linkedin", "status": "published" },
    {
      "network": "instagram",
      "status": "failed",
      "error_message": "Instagram account disconnected"
    }
  ]
}

Recovery: Fix Instagram connection in your dashboard, then create a new post for Instagram if needed.

Scenario 6: Automatic retry

Post status: processing → processed (job initiated)
Twitter API returns rate limit error
Platform status: failed_waiting_for_retry
System waits 1 minute, retries automatically
Twitter publishes successfully

During retry:

{
  "status": "processed",
  "platforms": [{
    "network": "twitter",
    "status": "failed_waiting_for_retry",
    "retry_after": "2024-01-15T10:01:00Z"
  }]
}

Timeline reference

Phase	Duration	Notes
Post creation	< 1 sec	Post created with initial status
Media processing (images)	1–15 sec	Post in `pending` status
Media processing (video)	10–120 sec	Depends on file size
Scheduling	Instant	Post → `scheduled` after media ready
Job initiation	< 1 sec	`processing` → `processed`
Platform publishing (text)	1–5 sec	Per platform
Platform publishing (images)	5–15 sec	Per platform
Platform publishing (video)	10–60 sec	Per platform
Retries	1–60 min	Exponential backoff, max 5 attempts
First insights	1+ hour	After platform reports `published`
Insight updates	2–12 hours	Varies by platform

Platform-specific notes

TikTok — May take 1–5 minutes for video processing on their end
YouTube — Large videos may take longer to upload
Instagram / Twitter / Facebook / LinkedIn — Usually fastest (1–10 seconds)

Filtering posts by status

Use the status query parameter to filter posts:

GET /api/posts?status=draft
GET /api/posts?status=scheduled
GET /api/posts?status=published
GET /api/posts?status=failed

Filter	What you get
`draft`	All draft posts
`scheduled`	Posts scheduled for the future
`published`	Successfully published posts (`status: "processed"`)
`failed`	Posts with at least one failed platform

Best practices

Check platform statuses

processed means jobs started, not completed. Always check individual platform statuses for actual publishing state.

Handle retries gracefully

Don’t alert users on first failure. Check for failed_waiting_for_retry and wait for automatic retries before reporting permanent failures.

Use webhooks

Instead of polling the API, subscribe to webhook events for instant notifications and fewer API calls.

Plan for partial failures

Posts can partially succeed — some platforms publish while others fail. Handle this in your UI and allow users to retry failed platforms.

Posts API Reference — Endpoint details for creating and managing posts
Platform Parameters — Platform-specific options
Webhooks — Webhook setup and event types