PostEverywhere Bulk Operations Guide

Two endpoints for working with many posts in one call:

• POST /v1/posts/bulk: create up to 50 posts in a single request
• POST /v1/posts/retry-failed: retry every failed destination matching a filter

The two differ in rate-limit cost. Bulk create is not a single hit today: the bulk endpoint charges your key once, then creates each post through the single-post path, which charges again per post, so a 50-post bulk consumes 51 of your 60-per-minute budget. Bulk retry is one hit. Per-post publishing limits still apply to each post individually.

Create up to 50 posts in one request: POST /v1/posts/bulk#

Each item is the same body you would send to POST /v1/posts, platform_content included, so X Articles, WordPress blog posts and Google Business Profile posts work in a batch too. An item that sends schedule_at fails with unsupported_schedule_at: read GET /v1/best-times and send the time as scheduled_for. (The MCP bulk_create_posts tool does take schedule_at: "best_time" per item and gives each post its own next best time.)

curl -X POST https://app.posteverywhere.ai/api/v1/posts/bulk \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      { "content": "Morning post",   "account_ids": [123, 456], "scheduled_for": "2026-08-01T09:00:00Z" },
      { "content": "Afternoon post", "account_ids": [123, 456], "scheduled_for": "2026-08-01T14:00:00Z" },
      { "content": "Evening post",   "account_ids": [123, 456], "scheduled_for": "2026-08-01T19:00:00Z" }
    ]
  }'

Bulk create response#

{
  "data": {
    "summary": { "total": 3, "succeeded": 2, "failed": 1 },
    "results": [
      { "index": 0, "ok": true,  "post": { "post_id": "...", ... } },
      { "index": 1, "ok": true,  "post": { "post_id": "...", ... } },
      { "index": 2, "ok": false, "error": { "code": "validation_error", "message": "scheduled_for must be in the future", "status": 400 } }
    ]
  },
  "error": null,
  "meta": { "request_id": "a1b2c3d4", "timestamp": "2026-06-11T09:55:12.341Z" }
}

Partial-success HTTP semantics#

• All succeeded → 201 Created
• All failed → 422 Unprocessable Entity
• Mixed → 207 Multi-Status

Always iterate results. Don't assume 200 means everything worked.

Bulk request limits#

• Max 50 posts per call. Exceeding returns 400 bulk_limit_exceeded.
• Retry safely by sending an Idempotency-Key header: a retry with the same key returns the original result instead of creating the posts again. See Make retries safe.
• Each post inside the array is validated independently: one bad entry doesn't kill the others. A caption over a platform's limit fails that item with content_too_long.
• Each post counts against your API rate limit and posting limits exactly like a single POST /v1/posts. There is no bulk discount.
• Posts are processed sequentially (not in parallel) to keep posting-rate-limits deterministic.

Retry every failed post at once: POST /v1/posts/retry-failed#

Retry every failed destination matching a filter. Avoids the "loop over N failed posts and retry each" anti-pattern.

# Retry every TikTok failure from yesterday
curl -X POST https://app.posteverywhere.ai/api/v1/posts/retry-failed \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform":     "tiktok",
    "failed_after": "2026-06-10T00:00:00Z",
    "failed_before":"2026-06-11T00:00:00Z"
  }'

Filter fields (at least one filter required)#

Field	Type	Description
post_ids	string[]	Up to 200 specific post UUIDs
account_id	number	Only failures on this social account
platform	string	One of instagram, facebook, x, linkedin, youtube, tiktok, threads, pinterest, bluesky, telegram, discord, wordpress, google_business
failed_after	ISO timestamp	Only failures with updated_at >= this
failed_before	ISO timestamp	Only failures with updated_at <= this
max_attempts	number	A modifier, not a filter: skip destinations whose attempt_count is already >= this. Sent on its own it returns 400 no_filter

If no filter is supplied, the endpoint returns 400 no_filter: refusing to retry the entire failure history is intentional.

Bulk retry response#

{
  "data": {
    "retried_count": 12,
    "destinations": [
      { "destination_id": "...", "post_id": "...", "platform": "tiktok", "new_status": "queued" },
      ...
    ],
    "message": "12 destinations queued for retry."
  },
  "error": null,
  "meta": { "request_id": "a1b2c3d4", "timestamp": "2026-06-11T09:55:12.341Z" }
}

Retried destinations have their attempts reset to 0, last_error cleared, and scheduled_for set to NOW() for immediate publish.

When bulk operations are worth using#

Schedule a 30-day content calendar#

const posts = generateContentPlan(30); // 30 post objects
const batches = chunk(posts, 50);      // Split into 50-post batches
for (const batch of batches) {
  await client.posts.bulkCreate(batch);
}

Resurrect everything that failed during an outage#

const outageStart = "2026-05-29T08:00:00Z";
const outageEnd   = "2026-05-29T20:30:00Z";

const result = await client.posts.retryFailed({
  failed_after:  outageStart,
  failed_before: outageEnd,
});
console.log(`Retrying ${result.retried_count} destinations`);

Recover one account after reconnecting#

// User just reconnected their Instagram. Retry recent IG failures.
await client.posts.retryFailed({
  account_id:   5356,
  failed_after: "2026-06-08T00:00:00Z",
});

Related: what bulk calls cost against your limit · dry-running a batch · per-item error codes · grouping a batch into a campaign · PostEverywhere API overview