# Post lifecycle

Every post status, how a post moves between them, what you can do in each state, and which webhook fires on each transition.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A post is `draft`, `scheduled` or `publishing`, then `published`, `partial` or `failed`. It becomes `cancelled` once every platform copy has been removed.

```
draft ──► scheduled ──► publishing ──► published
                            │      └──► partial
                            └─────────► failed
published / partial ──► cancelled   (via unpublish)
```

## First call

Read `post.status` with `GET /v1/posts/{postId}`, or get a [post webhook](/webhooks/social) on change. The post `status` aggregates the per-entry `status` in `platforms[]`.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: fetched } = await zernio.posts.getPost({
  path: { postId: '65f1c0a9e2b5af0012ab34cd' }
});

console.log(fetched.post.status);
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

fetched = client.posts.get_post(post_id="65f1c0a9e2b5af0012ab34cd")

print(fetched["post"]["status"])
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/posts/65f1c0a9e2b5af0012ab34cd" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "partial",
    "scheduledFor": "2027-01-01T17:00:00Z",
    "platforms": [
      {
        "platform": "linkedin",
        "status": "published",
        "platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"
      },
      {
        "platform": "instagram",
        "status": "failed",
        "errorMessage": "Media processing failed: video too short for Reels",
        "errorCategory": "user_content",
        "errorSource": "user"
      }
    ]
  }
}
```

## Post statuses

| Status | Meaning |
|--------|---------|
| `draft` | Saved. Default when you send no scheduling field. |
| `pending_approval` | Saved with `requiresApproval: true`. Never publishes until [reviewed](/posts/review-post) and approved. |
| `scheduled` | Future `scheduledFor`, set by you or a [queue](/guides/queue-scheduling). |
| `publishing` | Transient. A delete stops entries still `pending`, not `processing` or `uploading` ones. |
| `published` | Every platform target succeeded. |
| `partial` | Some platform targets succeeded, others failed. |
| `failed` | Every platform target failed. |
| `cancelled` | Account disconnected, or every copy removed with [unpublish](/posts/unpublish-post) (a delete removes the record instead). Editable and reschedulable like a draft. |

## Which status a new post gets

[Create post](/posts/create-post) picks it from the scheduling fields:

| You send | Initial status |
|----------|----------------|
| `publishNow: true` | Publishes in the request; the response holds the result (`published`, `partial` or `failed`) and `platformPostUrl` per platform. |
| `scheduledFor` | `scheduled`. A past time publishes at once, like `publishNow`. |
| `requiresApproval: true` with `scheduledFor` | `pending_approval`. Publishes only after approval. |
| `queuedFromProfile` | `scheduled`, with `scheduledFor` from the profile's next free queue slot. |
| `isDraft: true`, or none of the above | `draft`. `isDraft` wins over `publishNow` and `scheduledFor`. |

`publishNow` returns `201` when every platform published, `207` when at least one failed.

`207` is a `2xx`: `fetch(...).ok` is `true` and axios resolves. Branch on the status code or `post.status`, never on "did it throw".

## Per-platform status and errors

Entry `status`: `pending`, `processing`, `uploading`, `published`, `failed` or `cancelled`, plus `platformPostUrl` once published. Failed entries add `errorMessage` (readable), `errorCategory` and `errorSource`.

| `errorCategory` | Meaning | Fix |
|-----------------|---------|-----|
| `auth_expired` | Token expired or revoked | Have the user reconnect. [Account health](/accounts/get-all-accounts-health) catches this early. |
| `user_content` | Breaks platform constraints (format, length, media specs) | Fix it. See [platform requirements](/platforms). |
| `user_abuse` | Platform rate limits or spam detection | Slow down. See [rate limits](/guides/rate-limits). |
| `platform_rate_limit` | Platform throttling | Retried automatically. |
| `quota_exhausted` | Shared daily API quota empty | Resumes at the platform's quota reset. |
| `account_issue` | Account setup, such as the wrong account type | Fix it on the platform. |
| `platform_rejected` | Rejected for policy reasons | Change the content. |
| `platform_error` | Platform `5xx` or maintenance | Transient. Retry later. |
| `system_error` | Zernio-side issue (rare) | Retry, or contact support if it persists. |
| `unknown` | Unclassified | Inspect `errorMessage`. |

`errorSource` says who can fix it: `user` errors need action from you or your user; `platform` and `system` errors are worth retrying.

## What you can do in each state

| Operation | Allowed states | Notes |
|-----------|---------------|-------|
| [Update](/posts/update-post) | `draft`, `scheduled`, `failed`, `partial`, `cancelled` | A published post can only have its recycling config updated. |
| [Delete](/posts/delete-post) | Any except `published` | Removes the Zernio record, with no status change or webhook. A `published` post returns `400`; use [unpublish](/posts/unpublish-post). |
| [Review](/posts/review-post) | `pending_approval` | Approve schedules it (past its time: publishes within a couple of minutes); reject returns it to `draft`. |
| [Retry](/posts/retry-post) | `failed`, `partial` | Retries only the failed platforms. |
| [Unpublish](/posts/unpublish-post) | `published`, `partial` | Deletes it from one platform: Threads, Facebook, X, LinkedIn, YouTube (permanent), Pinterest, Reddit, Bluesky, Google Business Profile, Telegram. `cancelled` once every entry is removed, else `partial`. |
| [Edit published](/posts/edit-post) | `published` | Text only, not media. See the platform list below. |

**Edit published support.** X (platform value `twitter`), Discord, Facebook, Reddit, LinkedIn, Telegram, Pinterest, Google Business Profile, YouTube and Slack, each with its own rules:

- **X** requires X Premium and a 1-hour window.
- **Pinterest** edits are gated behind a Pinterest closed beta.
- **No edit API:** Instagram, Threads, TikTok, Snapchat, WhatsApp and Bluesky.

## Tracking transitions with webhooks

Each transition fires a [post webhook](/webhooks/social):

| Event | Fires when |
|-------|-----------|
| `post.scheduled` | Enters scheduled: created with a schedule, queued, promoted from draft, approved, or retried |
| `post.published` | All platforms succeeded |
| `post.partial` | Some platforms succeeded, some failed |
| `post.failed` | All platforms failed |
| `post.cancelled` | A scheduled post is cancelled because its account was disconnected |
| `post.recycled` | A recycled post is re-queued |
| `post.platform.published` / `post.platform.failed` | Per platform target, as soon as it reaches a terminal state |
| `post.tiktok.url_resolved` | A published TikTok post's public URL is available (TikTok resolves URLs asynchronously) |
| `post.platform.deleted` | A published platform target is detected as deleted on the platform (poll-driven, roughly hourly) |

## How it behaves

- **Per-platform events are fastest.** A post targeting 5 platforms emits them one by one; the aggregate event waits for all 5.
- **TikTok can hold the rollup for up to 48 hours.** A TikTok entry stays `uploading` while TikTok processes it, and the post stays `publishing`. The other entries fire `post.platform.published` or `post.platform.failed` meanwhile.
- **`publishNow: true` needs no webhook.** The synchronous create response holds the results and URLs.
- **Removed posts stay `published`.** An entry that disappears from the platform keeps `status: "published"` and gets `removedFromPlatformAt`. Detection runs with the analytics sync: up to a few hours of lag.
- **Retry skips published platforms.**
- **Zero content retention clears the text.** With [zero content retention](/security/zero-content-retention) on for the team or a profile, the text is cleared once publishing ends. A failed post cannot then be retried or updated, and recycling is not available.

## If it fails

| Error | Cause | Fix |
|---|---|---|
| `400` `invalid_resource_state` on `DELETE /v1/posts/{postId}` (`"Published posts cannot be deleted"`, `type: "invalid_request_error"`) | The post is `published`. | [Unpublish](/posts/unpublish-post) from each platform first, or keep the record as the source of `platformPostUrl` and analytics. |
| `422` on `POST /v1/posts/{postId}/retry` or `PUT /v1/posts/{postId}` of a failed post | [Zero content retention](/security/zero-content-retention) cleared the post text. | Create a new post. |

## Related

- [Error handling](/guides/error-handling): the error envelope and the retry endpoint.
- [Idempotency & safe retries](/guides/idempotency): avoid double-posting when you retry creates.
- [Queue scheduling](/guides/queue-scheduling): let Zernio assign the publish time.
- [Social webhooks](/webhooks/social): the payload of each event above.