Scheduling

Scheduling is the heart of TimeToPost: you decide what to say and when, and a background scheduler does the publishing — across Instagram, TikTok and X, from one post. This page explains the post lifecycle and how to let your own engagement data pick the time for you.

How a scheduled post works

When you schedule a post you give it content, target accounts, optional media, and a scheduledAt timestamp. The timestamp must be in the future — the API rejects past times, because the scheduler treats “scheduled time has arrived” as its trigger. A cron-style worker runs continuously, finds posts whose time has come, and publishes each one to every selected account, recording a result per account. One post can therefore fan out to several platforms with independent outcomes.

Post statuses

Every post carries one of six statuses. The three you will see most are DRAFT, SCHEDULED and PUBLISHED; the rest describe the moments in between and the failure modes. (The REST API returns these in lowercase, e.g. "status": "scheduled".)

Status	Meaning
DRAFT	Saved without a publish time. Drafts never publish on their own — edit and schedule them whenever you are ready.
SCHEDULED	Has a future publish time. The background scheduler will pick it up when scheduledAt arrives.
PUBLISHING	The scheduler is actively pushing the post to the selected platforms right now. Usually lasts a few seconds.
PUBLISHED	Every selected account received the post successfully. publishedAt is recorded.
FAILED	No account could be published to — for example an expired connection or a platform rejection. The per-account error is stored with the post result.
PARTIAL	A multi-account post where some accounts succeeded and others failed. Check the per-account results to see which ones need attention.

The typical happy path is DRAFT → SCHEDULED → PUBLISHING → PUBLISHED. A post created with a publish time skips the draft stage and starts at SCHEDULED; one created without a time is saved as a DRAFT. You can delete a scheduled post any time before it fires.

Optimal posting times

Generic “best time to post” charts are averages of other people’s audiences. TimeToPost instead ingests engagement metrics (likes, comments, shares, views) from your own published posts and scores every hour of the day and day of the week against them. The result is a per-account recommendation: your top five hours and top three days, each with an engagement score, plus how many data points back the recommendation. The more you publish, the sharper it gets.

In the composer this shows up as a suggested slot; over the API it is one call (available on plans that include best-time-to-post):

curl

curl https://timetopost.co/api/analytics/optimal-times?platform=instagram \
  -H "Authorization: Bearer ttp_your_token_here"

# Response (abridged)
{
  "success": true,
  "recommendation": {
    "bestHours": [{ "hour": 18, "score": 0.92 }, { "hour": 12, "score": 0.85 }],
    "bestDays":  [{ "day": "Tuesday", "score": 0.88 }],
    "dataPoints": 64
  }
}

Related endpoints give you optimal times per connected account, the next optimal slot from now, and a full weekly schedule — see the API reference.

Practical tips

Schedule in UTC when using the API (scheduledAt is an ISO 8601 timestamp); the dashboard converts to your local timezone for you.
Keep an eye on PARTIAL posts — usually one account’s token expired. Reconnect it and republish to just that account.
Batch a week of content in one sitting, then let optimal-times spread the posts across your audience’s peak hours.

Previous← Getting started NextIntegrations →