# Schedule

## Managing Scheduled Posts

Scheduled posts are created via [Publish Post](https://help.blotato.com/api/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](https://help.blotato.com/api/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`

```json
{
  "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](https://help.blotato.com/api/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

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

With pagination:

```http
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`

```json
{
  "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

```json
{
  "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](https://help.blotato.com/api/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

```json
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

```json
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](https://help.blotato.com/schedule-slots#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

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