Scheduled Posts

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.

---

List Scheduled Posts

Endpoint

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

URL: /schedules

Method: GET

Description

Returns the current user's scheduled posts, ordered by scheduled time (ascending). Only returns posts scheduled in the future. Supports cursor-based pagination.

Query Parameters

Field	Type	Required	Description
limit	integer	No	Number of scheduled posts to return per page. Max 100. Defaults to 20.
cursor	string	No	Pagination cursor from a previous response.

Response

Status Code: 200 OK

{
  "items": [
    {
      "id": "abc123",
      "scheduledAt": "2026-04-01T12:00:00.000Z",
      "draft": {
        "accountId": "98432",
        "content": {
          "text": "Scheduled tweet",
          "mediaUrls": [],
          "platform": "twitter"
        },
        "target": {
          "targetType": "twitter"
        }
      },
      "account": {
        "id": "98432",
        "name": "John Doe",
        "username": "johndoe",
        "profileImageUrl": "https://example.com/avatar.jpg",
        "subaccountId": null,
        "subId": null,
        "subaccountName": null
      }
    }
  ],
  "count": "1",
  "cursor": "eyJzY2hlZHVsZWRBdCI6..."
}

Response Keys

Field	Type	Description
items	array	Array of scheduled post objects.
items[].id	string	Scheduled post ID. Use this for get, update, and delete operations.
items[].scheduledAt	string	Scheduled time in ISO 8601 UTC.
items[].draft	object	The post content. Same structure as the post object in Publish Post.
items[].account	object or null	The target account info. null if the account has been disconnected.
count	string	Total number of future scheduled posts.
cursor	string	Pagination cursor. Present when there are more results. Pass as cursor query parameter to get the next page.

Example

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

---

Get Scheduled Post

Endpoint

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

URL: /schedules/:id

Method: GET

Description

Fetch a single scheduled post by its ID.

Path Parameters

Field	Type	Required	Description
id	string	Yes	The scheduled post ID from List Scheduled Posts.

Response

Status Code: 200 OK

{
  "schedule": {
    "id": "abc123",
    "scheduledAt": "2026-04-01T12:00:00.000Z",
    "draft": {
      "accountId": "98432",
      "content": {
        "text": "Scheduled tweet",
        "mediaUrls": [],
        "platform": "twitter"
      },
      "target": {
        "targetType": "twitter"
      }
    },
    "account": {
      "id": "98432",
      "name": "John Doe",
      "username": "johndoe",
      "profileImageUrl": "https://example.com/avatar.jpg",
      "subaccountId": null,
      "subId": null,
      "subaccountName": null
    }
  }
}

Status Code: 404 Not Found

{
  "message": "Schedule not found"
}

Example

GET https://backend.blotato.com/v2/schedules/abc123 HTTP/1.1
blotato-api-key: YOUR_API_KEY

---

Update Scheduled Post

Endpoint

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

URL: /schedules/:id

Method: PATCH

Description

Update a scheduled post's content, scheduled time, or both. At least one field must be provided. The scheduled time must be in the future. When the scheduled time is changed, the post is re-queued for publishing at the new time.

Path Parameters

Field	Type	Required	Description
id	string	Yes	The scheduled post ID from List Scheduled Posts.

Request Body

Field	Type	Required	Description
patch	object	Yes	The fields to update.
patch.draft	object	No	Updated post content. Same structure as the post object in Publish Post.
patch.scheduledTime	string	No	New scheduled time in ISO 8601 format. Must be in the future.

Response

Status Code: 204 No Content

Status Code: 404 Not Found

{
  "message": "Schedule not found"
}

Status Code: 422 Unprocessable Entity

{
  "message": "scheduledTime must be in the future"
}

Examples

Update Scheduled Time

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

{
  "patch": {
    "scheduledTime": "2026-05-01T15:00:00Z"
  }
}

Update Post Content

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

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

Update Both

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

{
  "patch": {
    "draft": {
      "accountId": "98432",
      "content": {
        "text": "New text, new time",
        "mediaUrls": [],
        "platform": "twitter"
      },
      "target": {
        "targetType": "twitter"
      }
    },
    "scheduledTime": "2026-06-01T09:00:00Z"
  }
}

---

Delete Scheduled Post

Endpoint

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

URL: /schedules/:id

Method: DELETE

Description

Delete a scheduled post. The associated publishing job is also cancelled. This action cannot be undone.

Path Parameters

Field	Type	Required	Description
id	string	Yes	The scheduled post ID from List Scheduled Posts.

Response

Status Code: 204 No Content

Example

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