Schedule and manage posts

Resolve the requested timezone, verify a scheduled result, manage the existing item, and avoid duplicate batch retries.

Prompt for your assistant:

Schedule this post for the date, time, and timezone I specify. Use my selected account, then show the resolved publish time. If I ask to change a scheduled post, find and update the existing schedule.

Create a schedule

1. Call blotato_list_accounts and select the destination.

2. Resolve the requested date and timezone, or choose the next free slot.

3. Call blotato_create_post with scheduledTime or useNextFreeSlot: true.

4. Verify the resolved scheduledTime and report it in the user's timezone. If no time is returned, retrieve status using the saved postSubmissionId before promising a schedule.

For REST, use POST /v2/posts with scheduling fields beside post. Follow Scheduling posts for the request layout and UTC rules.

Request and verification example

Use an authenticated connection. For “June 15, 2030 at 9 AM in America/Denver,” the resolved UTC time is 2030-06-15T15:00:00Z. Replace this example with the user's intended future date, accounting for daylight saving time on that date. Replace accountId with the selected Twitter/X account from lookup.

Call blotato_create_post once:

{
  "accountId": "98434",
  "platform": "twitter",
  "text": "Registration for our workshop opens today.",
  "mediaUrls": [],
  "scheduledTime": "2030-06-15T15:00:00Z"
}

For REST, send this body to POST https://backend.blotato.com/v2/posts with blotato-api-key: YOUR_API_KEY and Content-Type: application/json:

{
  "post": {
    "accountId": "98434",
    "content": {"platform": "twitter", "text": "Registration for our workshop opens today.", "mediaUrls": []},
    "target": {"targetType": "twitter"}
  },
  "scheduledTime": "2030-06-15T15:00:00Z"
}

Save the returned postSubmissionId. A REST acceptance response has this shape:

{
  "postSubmissionId": "123e4567-e89b-12d3-a456-426614174000",
  "scheduledTime": "2030-06-15T15:00:00Z"
}

If further verification is needed, call blotato_get_post_status with {"postSubmissionId": "RETURNED_ID"}, or request GET /v2/posts/RETURNED_ID with the authentication header. A scheduled result has this shape:

{
  "postSubmissionId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "scheduled",
  "scheduledTime": "2030-06-15T15:00:00Z"
}

Report “Scheduled for June 15 at 9 AM America/Denver,” not “Published.” For an unfinished result, wait at least 10 seconds between status checks and stop after a client wait budget, such as 2 minutes, with the saved ID and unresolved state. An uncertain result is not permission to create another post.

Change or cancel

1. Call blotato_list_schedules to locate the scheduled item.

2. Call blotato_get_schedule to read its content and time.

3. Call blotato_update_schedule with the intended change, or blotato_delete_schedule to cancel.

4. Verify and report the resulting schedule state.

For REST, use the corresponding GET, PATCH, or DELETE /v2/schedules/:id operation. See Scheduled Posts.

Scheduled-post IDs differ from submission and published-post IDs. Obtain the schedule ID from the listing. A scheduled result is the stopping point for this task. Publishing verification belongs after the scheduled time.

Stop conditions and batches

Do not assume the create response has status: "scheduled". A returned submission ID or a successful HTTP response alone does not establish the resolved schedule. Use the scheduling rules and post status.

Before useNextFreeSlot, verify slots exist for the intended destination. If no matching slot or available slot time is found, post creation returns a validation error. Do not remove the scheduling field and retry, since a request without scheduling publishes immediately.

For a batch, record each destination, resolved time, submission ID, schedule ID when available, and outcome. Retry only a confirmed failed item after correcting its cause. Do not recreate successful items because another item failed. Scheduling a set of posts does not create a recurring content-generation automation.