Scheduling

Every post either publishes now or at a time you choose. Scheduling uses the same POST /v1/posts endpoint, with scheduledFor in place of publishNow.

Schedule a post

curl -X POST https://social-publish-api.onrender.com/v1/posts \
  -H "x-access-key: $RELAYCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Webinar starts in one hour. Join us!",
    "targets": [{ "accountId": "8f1c2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b" }],
    "scheduledFor": "2026-10-20T15:00:00+02:00"
  }'

const publishAt = new Date("2026-10-20T13:00:00Z");

await fetch("https://social-publish-api.onrender.com/v1/posts", {
  method: "POST",
  headers: { "x-access-key": process.env.RELAYCAST_API_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({
    content: "Webinar starts in one hour. Join us!",
    targets: [{ accountId: "8f1c2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b" }],
    scheduledFor: publishAt.toISOString(), // "2026-10-20T13:00:00.000Z"
  }),
});

from datetime import datetime, timezone

publish_at = datetime(2026, 10, 20, 13, 0, tzinfo=timezone.utc)

requests.post(
    "https://social-publish-api.onrender.com/v1/posts",
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
    json={
        "content": "Webinar starts in one hour. Join us!",
        "targets": [{"accountId": "8f1c2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b"}],
        "scheduledFor": publish_at.isoformat(),  # "2026-10-20T13:00:00+00:00"
    },
)

The post is created with status: "scheduled" and its targets are queued. At the scheduled time the targets publish and the post moves through publishing to published, partial or failed.

Timestamp format

scheduledFor must be an ISO 8601 date-time with a time zone: either Z for UTC or an offset like +02:00 or -05:00.

The time is stored as an absolute instant and returned in UTC ("scheduledFor": "2026-10-20T13:00:00.000Z"). To post at a local wall-clock time, convert it in your code with the correct offset for that date, since daylight-saving changes alter the offset.

Rules

• Future times only. A scheduledFor more than a minute in the past is rejected with 400 validation_error and the message scheduledFor must be in the future. Times within that one-minute grace window publish right away.
• publishNow wins. If you send publishNow: true, any scheduledFor is ignored.
• One of the two is required. Sending neither returns 400 with Either publishNow or scheduledFor is required.
• Credits are reserved at creation, not at publish time. A scheduled post that can't be paid for is rejected immediately with 402. See Credits & Usage.
• Validation happens at creation. Content, media and options are checked when you schedule, so a valid scheduled post won't fail validation later. It can still fail at publish time for runtime reasons, such as a media URL that has stopped working or an account whose access was revoked.

Timing

Scheduled targets are queued with a delay and published by a background worker when that delay ends, usually within seconds of scheduledFor. If a job is missed (for example during an infrastructure restart), a sweeper re-queues targets that are still waiting a couple of minutes after their scheduled time.

Temporary platform errors are retried with backoff, so a target can publish some minutes after its scheduled time. See Idempotency & Retries.

Media for scheduled posts

Media is downloaded by the platform at publish time, not when you schedule. Make sure public URLs stay reachable until then, or upload the file to the media library and use a media:// reference. See Media & Uploads.

Changing or cancelling a scheduled post

The public API has no endpoint to edit or cancel a post. To cancel, delete the post from the Posts page in the dashboard before it publishes: its queued targets are removed and their credits refunded. To change it, delete it and create a new one. The post's Open in playground action loads the original request so you can adjust and resubmit it.

Get notified

Create a notification rule for post.scheduled to confirm when posts are scheduled, and for post.published, post.partial and post.failed to hear the outcome. Rules can be limited to scheduled posts only. See Notifications & Webhooks.

In the dashboard

The Playground has a date and time picker for scheduling, and the Posts page has a calendar view of everything scheduled and published.