How to Schedule Social Media Posts via API

Scheduling social media posts is essential for content planning, timezone targeting, and consistent publishing. Instead of building your own queue system and managing cron jobs for each platform, you can schedule posts across all major social platforms with a single API call using PostPeer.

This guide walks you through scheduling, managing, and monitoring scheduled posts.

How Scheduling Works

PostPeer's scheduling is simple: add a publish_at field to your post request with an ISO 8601 timestamp. PostPeer queues the post and publishes it at the specified time.

POST https://api.postpeer.dev/v1/posts

The scheduler handles:

• Timezone conversion — pass any valid ISO 8601 timestamp
• Platform rate limits — posts are queued to respect each platform's limits
• Automatic retries — if a platform is temporarily unavailable, PostPeer retries
• Webhook notifications — get notified when the post actually publishes

Step 1: Schedule a Post

Here's a basic scheduled post to Twitter and Facebook:

curl -X POST https://api.postpeer.dev/v1/posts \
  -H "x-access-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Good morning! Here is your Monday motivation.",
    "platforms": [
      { "platform": "twitter", "accountId": "acc_tw_123" },
      { "platform": "facebook", "accountId": "acc_fb_456" }
    ],
    "publish_at": "2026-04-07T08:00:00Z"
  }'

The response confirms the post is scheduled:

{
  "postId": "post_xyz789",
  "status": "scheduled",
  "publishAt": "2026-04-07T08:00:00Z",
  "platforms": [
    { "platform": "twitter", "status": "pending" },
    { "platform": "facebook", "status": "pending" }
  ]
}

Step 2: Schedule With Media

Scheduled posts support all the same media options as immediate posts:

curl -X POST https://api.postpeer.dev/v1/posts \
  -H "x-access-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product drop this Friday!",
    "mediaItems": [
      { "url": "https://cdn.example.com/product-launch.mp4", "type": "video" }
    ],
    "platforms": [
      { "platform": "tiktok", "accountId": "acc_tt_123" },
      { "platform": "instagram", "accountId": "acc_ig_456" },
      { "platform": "youtube_shorts", "accountId": "acc_yt_789" }
    ],
    "publish_at": "2026-04-11T14:00:00Z"
  }'

Media is downloaded and validated at scheduling time, so you'll know immediately if there are format issues.

Step 3: Schedule a Content Calendar

For batch scheduling, make multiple API calls to build out your content calendar:

const posts = [
  {
    content: "Monday tip: Start your week with planning.",
    publishAt: "2026-04-07T09:00:00Z",
  },
  {
    content: "Wednesday insight: Data-driven decisions matter.",
    publishAt: "2026-04-09T09:00:00Z",
  },
  {
    content: "Friday wrap-up: What we shipped this week.",
    publishAt: "2026-04-11T16:00:00Z",
  },
];

for (const post of posts) {
  const response = await fetch("https://api.postpeer.dev/v1/posts", {
    method: "POST",
    headers: {
      "x-access-key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: post.content,
      platforms: [
        { platform: "twitter", accountId: "acc_tw_123" },
        { platform: "threads", accountId: "acc_th_456" },
      ],
      publish_at: post.publishAt,
    }),
  });

  const result = await response.json();
  console.log(`Scheduled: ${result.postId} for ${post.publishAt}`);
}

Step 4: Monitor Delivery With Webhooks

Set up a webhook endpoint to get notified when scheduled posts publish:

{
  "event": "post.published",
  "postId": "post_xyz789",
  "platform": "twitter",
  "platformPostUrl": "https://x.com/youruser/status/987654321",
  "publishedAt": "2026-04-07T08:00:03Z"
}

You'll also get notified if a scheduled post fails:

{
  "event": "post.failed",
  "postId": "post_xyz789",
  "platform": "facebook",
  "error": "Account token expired",
  "failedAt": "2026-04-07T08:00:02Z"
}

Best Practices

Timezone Handling

Always pass timestamps in UTC (with the Z suffix) and handle timezone conversion on your end. This avoids ambiguity:

// Good - UTC
"publish_at": "2026-04-07T15:00:00Z"

// Also good - explicit offset
"publish_at": "2026-04-07T10:00:00-05:00"

Schedule Buffer

Schedule posts at least 5 minutes in the future. Posts scheduled too close to the current time may be published immediately rather than queued.

Content Validation

PostPeer validates content against platform rules at scheduling time. You'll get immediate feedback if content exceeds character limits or media doesn't meet requirements.

Monitoring

Use webhooks rather than polling to track delivery. Webhooks are more efficient and give you real-time status updates.

What's Next

• Platform-specific scheduling: Use platformSpecificData to customize content per platform
• Analytics: Pull engagement data after posts publish to optimize your schedule
• Cross-posting patterns: See our guide on posting to multiple platforms

Check out the PostPeer docs for the full API reference, or sign up for free to start scheduling.