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.

The web app does not have a built-in calendar filter for one brand, account, or page. To build a custom filtered calendar, list scheduled posts with this endpoint, then filter the returned items by account.id, account.subaccountId, account.subId, or account.subaccountName.

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

{
  "items": [
    {
      "id": "sch_abc123",
      "scheduledAt": "2026-04-01T14:00:00.000Z",
      "account": {
        "id": "98432",
        "name": "Jane Smith",
        "username": "janesmith",
        "profileImageUrl": "https://...",
        "subaccountId": null,
        "subId": null,
        "subaccountName": null
      },
      "draft": {
        "accountId": "98432",
        "content": {
          "text": "Scheduled post content",
          "mediaUrls": [],
          "platform": "twitter"
        },
        "target": {
          "targetType": "twitter"
        }
      }
    }
  ],
  "count": "12",
  "cursor": "eyJzY2hlZHVsZWRBd..."
}

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

GET https://backend.blotato.com/v2/schedules?limit=10 HTTP/1.1
blotato-api-key: YOUR_API_KEY

With pagination:

GET https://backend.blotato.com/v2/schedules?limit=10&cursor=eyJzY2hlZHVsZWRBd... HTTP/1.1
blotato-api-key: YOUR_API_KEY

---

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

{
  "schedule": {
    "id": "sch_abc123",
    "scheduledAt": "2026-04-01T14:00:00.000Z",
    "account": {
      "id": "98432",
      "name": "Jane Smith",
      "username": "janesmith",
      "profileImageUrl": "https://...",
      "subaccountId": null,
      "subId": null,
      "subaccountName": null
    },
    "draft": {
      "accountId": "98432",
      "content": {
        "text": "Scheduled post content",
        "mediaUrls": [],
        "platform": "twitter"
      },
      "target": {
        "targetType": "twitter"
      }
    }
  }
}

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

{
  "patch": {
    "scheduledTime": "2026-04-05T10:00:00Z",
    "draft": {
      "accountId": "98432",
      "content": {
        "text": "Updated post content",
        "mediaUrls": [],
        "platform": "twitter"
      },
      "target": {
        "targetType": "twitter"
      }
    }
  }
}

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

PATCH https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1
Content-Type: application/json
blotato-api-key: YOUR_API_KEY

{
  "patch": {
    "scheduledTime": "2026-04-05T10:00:00Z"
  }
}

Update the post text

PATCH https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1
Content-Type: application/json
blotato-api-key: YOUR_API_KEY

{
  "patch": {
    "draft": {
      "accountId": "98432",
      "content": {
        "text": "New text for this scheduled post",
        "mediaUrls": [],
        "platform": "twitter"
      },
      "target": {
        "targetType": "twitter"
      }
    }
  }
}

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:

1. POST /v2/schedule/slots/next-available
   Body: { "platform": "twitter", "accountId": "98432" }
   Response: { "slot": { "slotId": "slot_1", "slotTime": "2026-04-02T09:00:00Z" } }

2. PATCH /v2/schedules/sch_abc123
   Body: { "patch": { "scheduledTime": "2026-04-02T09:00:00Z" } }

---

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

DELETE https://backend.blotato.com/v2/schedules/sch_abc123 HTTP/1.1
blotato-api-key: YOUR_API_KEY