Start scheduling posts

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Hands the app's approved posts to the publisher, so each one goes out at its own scheduled time.

The work runs in the background. Poll Get scheduling job with the returned job_id to see how it went. Starting a second run for the same app while the first one is still starting is refused.

Calling it again for the same window normally returns the job already in flight instead of starting a second one, but treat that as best-effort rather than a guarantee. A retry sent in the moment before the job starts running can come back with a new job_id. Nothing is published twice when that happens, because both runs resolve the same automation for a given post.

It takes the posts whose scheduled_at falls in [scheduled_from, scheduled_until) and that aren't handed over yet, which means the posts you approved plus the ones an earlier run couldn't place. A post still in proposal isn't taken at all, so approve it first.

Placing a post can fail for reasons this endpoint can't check up front, and each one is counted in the job's result rather than failing the request:

The workspace is on the free plan. Publishing scheduled posts needs a paid workspace plan, and those posts are counted in plan_limited.
The app has no connected account for the post's platform with publishing permission, or it has more than one. Those posts move to needs_reconnect and are counted there, and a later run picks them up once you fix the connection.
The post's platform can't be published to at all, or its scheduled time has already passed. Those posts move to failed, which is final.

post/api/apps/{app_id}/social-calendar/posts/schedule

Path parameters

app_idstring required

ID of the app whose social calendar you want.

Request body

scheduled_fromstring date-time required

Start of the range to schedule, inclusive, as an ISO 8601 timestamp carrying an offset.

scheduled_untilstring date-time required

End of the range, exclusive, as an ISO 8601 timestamp carrying an offset. It has to be later than scheduled_from.

Example request

{
  "scheduled_from": "2026-09-01T00:00:00Z",
  "scheduled_until": "2026-10-01T00:00:00Z"
}

Response

The scheduling job that is now running, or the one already in flight for this range.

job_idstring required

ID of the scheduling job. Pass it as job_id to Get scheduling job.

statusstring required

State of the job. Either pending, running, completed, or failed. See Scheduling jobs for what each value means. A range holding nothing to schedule comes back completed straight away.

Example response

{
  "job_id": "68a1c4f0d21b4e0a3c77e912",
  "status": "pending"
}