Scheduling and repeats

Schedule a post for a set time in any timezone, add it to a profile's queue, repeat it daily, weekly or monthly, and edit, cancel or hold it for approval.

Every posting endpoint takes the same timing fields. Leave them out and the post goes now; add scheduled_date for a set time, add_to_queue=true for the profile's next free slot, or repeat_every and repeat_times for a series.

curl -X POST https://api.reelspan.com/v1/posts/video \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "user=my-brand" \
  -F "platform[]=tiktok" \
  -F "platform[]=instagram" \
  -F "title=Launch day" \
  -F "scheduled_date=2026-12-01T09:00:00" \
  -F "timezone=Europe/London" \
  -F "[email protected]"

import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const post = await reelspan.posts.video({
  user: 'my-brand',
  platforms: ['tiktok', 'instagram'],
  title: 'Launch day',
  video: { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  scheduledDate: '2026-12-01T09:00:00',
  timezone: 'Europe/London',
});
console.log(post.job_id);

from reelspan import Reelspan

reelspan = Reelspan()
post = reelspan.posts.video("my-brand", ["tiktok", "instagram"], "launch.mp4", "Launch day",
                            scheduled_date="2026-12-01T09:00:00", timezone="Europe/London")
print(post["job_id"])

A scheduled post answers 202 at once:

{ "success": true, "job_id": "sched_3Jd9aQ…", "request_id": "9b1f6c2e8a3d4f50b7e1c9a2d6f3e8b1", "scheduled_date": "2026-12-01T09:00:00.000Z" }

Keep the job_id: it is how you edit or cancel the post. scheduled_date in the answer is always UTC.

The time and the timezone

scheduled_date is ISO 8601. With an offset or Z (2026-12-01T09:00:00+01:00, 2026-12-01T08:00:00Z) that exact moment is used and timezone is ignored for it.
Without an offset (2026-12-01T09:00:00, or a bare date, which means midnight), the time is read in timezone, an IANA name such as America/New_York or Asia/Kolkata. Without timezone, the workspace's default time zone is used, and UTC when none is set. Daylight-saving changes are handled.
The time must be in the future and within 365 days. An unknown timezone or an unreadable date is refused with 400.

The media is uploaded and checked when you schedule, and the monthly upload count is taken then too (one per network). Whether each network's account is connected is checked when the post runs, so you can schedule for an account you will connect later; if it is still missing at that time, that network is skipped with profile_platform_mapping_invalid.

The queue

Send add_to_queue=true instead of a date, and the post takes the profile's next open posting slot within the next 30 days. The answer is the same 202, with the chosen time in queue_slot. max_posts_per_slot (1 to 100) overrides how many posts one slot may hold for this request. scheduled_date and add_to_queue can't be used together.

Set a profile's slots, days and capacity with the queue endpoints; see Queue. A full queue answers 400 with QUEUE_FULL.

Repeating posts

repeat_every (day, week or month) with repeat_times (2 to 30, the first post included) creates the whole series at once:

curl -X POST https://api.reelspan.com/v1/posts/text \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user": "my-brand", "platform": ["x", "linkedin"], "title": "Office hours are open: reply with your questions",
       "scheduled_date": "2026-12-07T16:00:00", "timezone": "America/New_York",
       "repeat_every": "week", "repeat_times": 6}'

await reelspan.posts.text({
  user: 'my-brand',
  platforms: ['x', 'linkedin'],
  title: 'Office hours are open: reply with your questions',
  scheduledDate: '2026-12-07T16:00:00',
  timezone: 'America/New_York',
  repeatEvery: 'week',
  repeatTimes: 6,
});

reelspan.posts.text("my-brand", ["x", "linkedin"], "Office hours are open: reply with your questions",
                    scheduled_date="2026-12-07T16:00:00", timezone="America/New_York",
                    repeat_every="week", repeat_times=6)

The first post is at scheduled_date (or the queue slot, or now if you give neither). Each later one keeps the same local time in the timezone, so a 4 pm post stays at 4 pm across daylight-saving changes.
A monthly series on the 29th, 30th or 31st falls on the last day of shorter months.
The last post must be within 365 days.
Every post in the series is its own scheduled post, with its own job_id, listed in the response under repeat.posts, alongside repeat.series_id. Each can be edited or cancelled on its own.
Each post counts as an upload per network. On a plan with a monthly limit, a series that would go over it is refused up front with 429 USAGE_LIMIT.

Listing, editing and cancelling

Task	Call
List upcoming posts	`GET /v1/scheduled` (filter with `profile_username`, `from`, `to`; page with `limit` up to 200 and `offset`)
Read one	`GET /v1/scheduled/{job_id}`
Change the time or text	`PATCH /v1/scheduled/{job_id}`
Cancel	`DELETE /v1/scheduled/{job_id}`

curl -X PATCH https://api.reelspan.com/v1/scheduled/sched_3Jd9aQ \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_date": "2026-12-02T09:00:00", "timezone": "Europe/London", "fields": {"tiktok_title": "Launch day, take two"}}'

await reelspan.scheduled.edit('sched_3Jd9aQ', { scheduled_date: '2026-12-02T09:00:00', timezone: 'Europe/London', fields: { tiktok_title: 'Launch day, take two' } });
await reelspan.scheduled.cancel('sched_3Jd9aQ', { withLaterRepeats: true });

reelspan.scheduled.edit("sched_3Jd9aQ", scheduled_date="2026-12-02T09:00:00", timezone="Europe/London", fields={"tiktok_title": "Launch day, take two"})
reelspan.scheduled.cancel("sched_3Jd9aQ", with_later_repeats=True)

Edit: change scheduled_date, timezone, title, description, or any other field through fields (a null value removes a field). The profile, networks and media can't change (user, platform[], video, photos[] and request_id are refused); cancel and post again for that. A new time must be at least a minute ahead. Moving a queued post to a set time takes it out of the queue.
Cancel: the post is stopped and its upload count refunded. Add ?series=rest (SDK: withLaterRepeats / with_later_repeats) to also cancel the later posts of its repeating series.
Too late: once a post has started publishing, or is due within a minute, both calls answer 409 scheduled_post_in_progress.

Holding posts for client approval

An agency can put scheduled posts in an approval link and send it to a client, who opens it without an account and approves each post or asks for changes.

curl -X POST https://api.reelspan.com/v1/approval-links \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_username": "my-brand", "job_ids": ["sched_3Jd9aQ", "sched_8kLw2P"], "title": "December posts", "expires_in_days": 14}'

A post in a link does not publish until the client approves it. When its time comes and it is not approved, it waits.
Approving a post whose time has already passed publishes it at once.
A post held for approval can still be edited after its time has passed. Editing a post that was approved, or had changes requested, sends it back to the client for approval.
Deleting the link lets its posts publish as scheduled.
A link holds up to 100 posts of one profile, and is valid for expires_in_days (1 to 60, default 14). Putting a post in a new link takes it out of any earlier one.

See Approval links for the full calls.

Seeing scheduled posts run

When a scheduled post runs, it behaves like any other post: each network's result appears in Post status (by job_id or request_id) and in an upload_completed webhook.

Something unclear or missing? Write to [email protected] and we’ll fix the page.