Post lifecycle

A post has one overall status and one status per entry in platforms. The overall status is a summary of the entries: a post is published only when every entry published, and partial when some did and some did not. This page lists every status, the moves between them and the webhook that tells you about each move.

#Overall statuses

#How a post moves

The main path is short:

draft ──► scheduled ──► publishing ──┬──► published
                                     ├──► partial
                                     └──► failed

Everything else is a side door into or out of that path:

A publishNow post, or one whose scheduledFor is already in the past, goes straight from the request to publishing and comes back as published, partial or failed.

#Per-platform statuses

Each entry in post.platforms has its own status:

An entry can be deleted on the platform after it published, for example when the owner removes it in the Instagram app. The entry keeps status: "published" and gains removedFromPlatformAt, and a post.platform.deleted webhook fires. Detection runs in the background roughly every hour, so expect some delay.

#Read the status

curl https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88 \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const entry of data.post.platforms) {
  console.log(entry.platform, entry.status, entry.errorCategory ?? "");
}

resp = requests.get(
    "https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    timeout=30,
)
for entry in resp.json()["post"]["platforms"]:
    print(entry["platform"], entry["status"], entry.get("errorCategory", ""))

{
  "post": {
    "_id": "6721a8c04e9b2f1d7c3a5e88",
    "status": "partial",
    "scheduledFor": "2026-11-03T08:30:00.000Z",
    "platforms": [
      {
        "platform": "linkedin",
        "accountId": "6710c3e2a9f14b0d8e5c7a21",
        "status": "published",
        "platformPostUrl": "https://www.linkedin.com/feed/update/urn:li:share:7254471109021356032"
      },
      {
        "platform": "instagram",
        "accountId": "6710c3e2a9f14b0d8e5c7a22",
        "status": "failed",
        "errorMessage": "The video is too short to publish as a Reel.",
        "errorCategory": "user_content",
        "errorSource": "user"
      }
    ]
  }
}

For anything that changes after creation, prefer webhooks to polling. Use GET /v1/posts with updatedSince to reconcile after downtime.

#Why an entry failed

Failed entries carry a readable errorMessage and two fields you can branch on. errorSource says who can fix it, and errorCategory says what kind of problem it is. Some entries also carry platformError with the platform's own code, subcode and message.

#Retry a failed post

POST /v1/posts/{postId}/retry publishes the failed entries of a failed or partial post again. Entries that already published are left alone, so a retry never double-posts.

curl -X POST https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88/retry \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88/retry", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.post.status);

resp = requests.post(
    "https://api.pozy.ai/v1/posts/6721a8c04e9b2f1d7c3a5e88/retry",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    timeout=60,
)
print(resp.json()["post"]["status"])

Fix user errors before you retry, otherwise the same error comes back. For a content fix, update the post with PUT /v1/posts/{postId} first, then retry.

#What you can do in each status

#Webhooks for each change

Exactly one of post.published, post.partial and post.failed fires each time a post publishes. Per-entry events usually arrive first, but do not rely on the order: see Webhook idempotency and ordering.

#Endpoints

#Webhook events