Guides

Scheduling posts

Add a scheduledAt and the post is queued and fires later. Credits are charged when it publishes. Not when you schedule it. Invalid media (an oversized image, a dead connection) is refused at create time, not at 7am. A TikTok PNG is converted to JPEG at create, with a warning.

Schedule a post

Send an ISO-8601 timestamp. UTC with a trailing Z still works. For a wall-clock time in a named zone, pass timezone (IANA) with a naive scheduledAt. The stored fire time is always UTC. The post comes back with state: "scheduled".

{
  "text": "Friday recap",
  "accounts": ["acc_123"],
  "scheduledAt": "2026-08-13T07:00:00",
  "timezone": "Europe/London"
}

That queues for 07:00 BST (06:00 UTC). The response includes scheduledAt in UTC and scheduledAtLocal in the zone you named. Existing posts that were stored as UTC are unchanged.

A naive datetime without timezone is a 400 unless the account has a default timezone (PATCH /v1/me with { "timezone": "Europe/London" }). "7am" with a trailing Z is 7am UTC, which is 8am in British Summer Time. If the account has a default timezone, a trailing-Z time is still that UTC instant; the zone is stored only so lists can show local time.

Timezones

Prefer timezone plus a naive local time when a person said "7am UK". Convert yourself only when you already have a UTC instant. Set an account default once if every post is in the same zone:

PATCH /v1/me
{ "timezone": "Europe/London" }

Then a naive scheduledAt of 2026-08-13T07:00:00 is 07:00 London without repeating the zone on every call.

{
  "scheduledAt": "2026-08-13T07:00:00",
  "timezone": "Europe/London"
}

Edit or cancel before it fires

While a post is scheduled you can change it or pull it entirely, by id:

PATCH can change text, media, mediaAlt, mediaOverrides, platformOptions, scheduledAt and timezone. Destinations stay fixed. platformOptions merge per platform, so { "tiktok": { "title": "…" } } does not wipe other TikTok fields. Cancelling frees the Idempotency-Key that created the post, so a retry with the same key creates the replacement instead of replaying the cancelled one.

GET /v1/posts (and MCP list_posts) accept ?account=acc_… and ?profile=<username> to show one channel or one profile. Unknown values are 404. Scheduled times in list views always include UTC; when a zone is known they read like 2026-08-14 07:00 Europe/London (06:00 UTC).

What happens at fire time

At the scheduled moment the post moves scheduled → processing → published (or partial / failed). Credits are debited then, only for targets that publish. If a target fails at fire time it's marked failed with an error and costs nothing. Subscribe to webhooks to be notified when a scheduled post fires, without polling.