Schedule

Managing Scheduled Posts

Scheduled posts are created via Publish Post using scheduledTime or useNextFreeSlot. These endpoints let you list, inspect, update, and delete scheduled posts before they publish.

To manage the recurring time slots themselves (the calendar grid), see Schedule Slots.


List Scheduled Posts

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /schedules

Method: GET

Description

Returns all scheduled posts for the current user. Only future posts are returned, ordered by scheduled time (ascending). Supports cursor-based pagination.

Query Parameters

Field
Type
Required
Description

limit

integer

No

Number of items per page. Min: 1, Max: 50. Default: 20.

cursor

string

No

Pagination cursor from a previous response.

Response

Status Code: 200 OK

Field
Type
Description

items

array

List of scheduled posts

items[].id

string

Schedule ID. Use this for get, update, and delete operations.

items[].scheduledAt

string

ISO 8601 UTC timestamp for when the post will publish.

items[].account

object or null

The target social account. Null if the account was disconnected.

items[].draft

object

The post payload. Same structure as the post object in Publish Post.

count

string

Total number of future scheduled posts.

cursor

string

Pagination cursor. Pass this as the cursor query parameter to fetch the next page. Absent when there are no more pages.

Example

With pagination:


Get Scheduled Post

Endpoint

URL: /schedules/:id

Method: GET

Description

Returns a single scheduled post by ID.

Path Parameters

Field
Type
Required
Description

id

string

Yes

Schedule ID from the List Scheduled Posts endpoint.

Response

Status Code: 200 OK

Returns 404 if the schedule does not exist or belongs to another user.


Update Scheduled Post

Endpoint

URL: /schedules/:id

Method: PATCH

Description

Update a scheduled post's content, scheduled time, or both. At least one field is required. The scheduled time must be in the future.

When the scheduled time changes, the publishing job is re-queued for the new time.

Path Parameters

Field
Type
Required
Description

id

string

Yes

Schedule ID from the List Scheduled Posts endpoint.

Request Body

Field
Type
Required
Description

patch.scheduledTime

string

No

New ISO 8601 timestamp. Must be in the future.

patch.draft

object

No

Updated post payload. Same structure as the post object in Publish Post. When provided, send the full object -- partial updates are not supported.

Response

Status Code: 204 No Content

Errors

Status
Reason

404

Schedule not found

422

Empty patch, invalid date, or scheduled time is in the past

Examples

Reschedule to a new time

Update the post text

Reschedule to the next available slot

The update endpoint does not accept useNextFreeSlot. To move a post to the next available slot, first call Find Next Available Slot, then pass the returned time as scheduledTime:


Delete Scheduled Post

Endpoint

URL: /schedules/:id

Method: DELETE

Description

Delete a scheduled post and cancel its publishing job. This action cannot be undone.

Path Parameters

Field
Type
Required
Description

id

string

Yes

Schedule ID from the List Scheduled Posts endpoint.

Response

Status Code: 204 No Content

Example

Last updated