Post Lifecycle

Understanding how posts move through different states in Outstand is crucial for building robust integrations. This guide explains the post lifecycle, status fields, timing expectations, and where to find error information.

Post States

Every post in Outstand goes through a lifecycle from creation to publication. The state is tracked both at the post level and at the per-account level.

Post-Level Status

At the post level, the publishedAt field indicates whether any account has successfully published:

Field	Type	Description
`publishedAt`	`datetime \| null`	Set when the first social account successfully publishes. `null` if no accounts have published yet.
`scheduledAt`	`datetime \| null`	When the post is scheduled to publish. `null` for immediate publishing.

Per-Account Status

Each social account attached to a post has its own publishing status:

Field	Type	Description
`status`	`'pending' \| 'published' \| 'failed'`	Current publishing state for this account.
`error`	`string \| null`	Error message if publishing failed. `null` otherwise.
`platformPostId`	`string \| null`	The platform-specific post ID after successful publish.
`publishedAt`	`datetime \| null`	When this account successfully published.

State Transitions

pending

When a post is created and scheduled, each social account starts in the pending state. The publishing worker will attempt to publish to each account when the scheduled time arrives (or immediately if no scheduledAt is specified).

published

When publishing succeeds for a social account:

status is set to published
platformPostId is populated with the platform-specific ID (e.g., Twitter post ID, Instagram media ID)
publishedAt is set to the current timestamp
error is set to null

failed

When publishing fails for a social account:

status is set to failed
error contains the error message from the platform
platformPostId remains null
publishedAt remains null

Timing Expectations

Scenario	Expected Timing
Post creation	Immediate response with post ID
Immediate publish (no `scheduledAt`)	Publishing starts within seconds
Scheduled publish	Publishing starts at the scheduled time (±30 seconds)
Status visibility via API	Available immediately after publishing completes
Webhook delivery	Sent within seconds of publishing completion

Note: Publishing to a social account typically takes 1-10 seconds depending on the platform and whether media upload is required. For posts with multiple accounts, each account is processed sequentially.

Where to Find Errors

Outstand provides two ways to get error information:

1. API Response (Polling)

Use GET /v1/posts/{id} to check the status of a post. Each social account in the response includes status, error, platformPostId, and publishedAt fields:

{
  "success": true,
  "post": {
    "id": "9dyJS",
    "publishedAt": "2025-01-15T10:30:00Z",
    "socialAccounts": [
      {
        "id": "abc123",
        "network": "facebook",
        "username": "MyPage",
        "status": "failed",
        "error": "Failed to upload Facebook photo from buffer: 400 - (#100) Invalid image",
        "platformPostId": null,
        "publishedAt": null
      },
      {
        "id": "def456",
        "network": "x",
        "username": "@myaccount",
        "status": "published",
        "error": null,
        "platformPostId": "1234567890123456789",
        "publishedAt": "2025-01-15T10:30:02Z"
      }
    ]
  }
}

2. Webhooks (Push)

If you've configured webhooks, you'll receive real-time notifications when publishing completes:

post.published - Sent when at least one account succeeds:

{
  "event": "post.published",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "postId": "9dyJS",
    "socialAccounts": [
      {
        "network": "x",
        "username": "@myaccount",
        "platformPostId": "1234567890123456789"
      },
      {
        "network": "facebook",
        "username": "MyPage",
        "error": "Failed to upload..."
      }
    ]
  }
}

post.error - Sent when ALL accounts fail:

{
  "event": "post.error",
  "timestamp": "2025-01-15T10:30:05Z",
  "data": {
    "postId": "9dyJS",
    "socialAccounts": [
      {
        "network": "facebook",
        "username": "MyPage",
        "error": "Access token has expired"
      }
    ]
  }
}

See the Webhooks documentation for setup instructions.

Best Practices

Use webhooks for real-time updates: Instead of polling, configure webhooks to receive immediate notifications when publishing completes or fails.
Check per-account status: A post can partially succeed - some accounts may publish while others fail. Always check the status field for each social account.
Handle retries: If publishing fails due to a transient error (rate limit, temporary outage), you can delete the failed post and create a new one.
Store platform IDs: After successful publishing, store the platformPostId returned for each account. You'll need this for analytics, comments, and other platform-specific operations.
Monitor for token expiration: Common errors like "Access token has expired" indicate the need to reconnect the social account.

Post Lifecycle

On this page