Scheduling Logic

Understanding how SchedPilot interprets dates, timezones, and platform constraints will help you build integrations that publish exactly when and where you intend.

How scheduled_date and timezone Work​

When you create a post, you supply a scheduled_date string and an optional timezone. SchedPilot interprets the date in the given timezone and stores it internally as UTC.

Example:

{
  "scheduled_date": "2024-06-15 09:00:00",
  "timezone": "America/New_York"
}

New York is UTC-4 in summer (Eastern Daylight Time), so this post will be published at 13:00 UTC on June 15, 2024.

Timezone format​

Always use IANA timezone names — do not use UTC offset strings.

A full list of IANA names is available at IANA Time Zone Database or via the Wikipedia timezone list.

Default timezone​

If no timezone field is supplied, SchedPilot assumes UTC.

Minimum Scheduling Window​

Posts must be scheduled at a point in the future. Submitting a scheduled_date that is in the past or only a few seconds ahead may result in one of two outcomes depending on how close the date is to the current time:

• The post publishes immediately upon saving.
• The publish attempt fails because the scheduler window has already passed.

To avoid ambiguity, always schedule posts at least 5 minutes in the future.

Platform Character Limits​

Exceeding a platform's character limit will cause the post to fail at publish time. Validate content length before submitting.

const MAX_LENGTHS = {
  twitter:   280,
  bluesky:   300,
  threads:   500,
  instagram: 2200,
  linkedin:  3000,
  facebook:  63206,
};

function validateContent(content, platform) {
  const limit = MAX_LENGTHS[platform];
  if (!limit) return true; // unknown platform, skip check
  return content.length <= limit;
}

Image Recommendations by Platform​

Post Statuses​

Handling Failed Posts​

When a post transitions to failed status, a post.failed webhook event is fired (if webhooks are configured). The error_message field in the payload describes what went wrong.

Common failure reasons and remedies:

Failed posts are not automatically retried. Once you have resolved the underlying issue, reschedule the post via the Create Post endpoint or from the dashboard.