Scheduling posts - SocialAPI.AI

Schedule a post by passing the scheduled_at field to POST /v1/posts. SocialAPI holds the post and publishes it at the scheduled time. Multi-platform fan-out works the same way as immediate publishing: one post object, multiple targets, one scheduled time applied to all of them.

How scheduling works

Set scheduled_at to an ISO 8601 timestamp in the future. SocialAPI validates the request immediately and queues it for delivery at the specified time.

curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Launching next week.",
    "targets": [
      { "account_id": "acc_instagram_01" },
      { "account_id": "acc_facebook_01" }
    ],
    "scheduled_at": "2026-06-01T09:00:00Z"
  }'

Response:

{
  "id": "p_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "status": "scheduled",
  "scheduled_at": "2026-06-01T09:00:00Z",
  "targets": [
    { "account_id": "acc_instagram_01", "platform": "instagram", "status": "scheduled" },
    { "account_id": "acc_facebook_01", "platform": "facebook", "status": "scheduled" }
  ]
}

To publish immediately instead of scheduling, pass "publish_now": true. Passing neither scheduled_at nor publish_now saves the post as a draft (even when targets are provided), it is not published.

Managing scheduled posts

List scheduled posts

Filter by status to see all upcoming posts:

curl "https://api.social-api.ai/v1/posts?status=scheduled" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Edit or reschedule a post

Use PATCH /v1/posts/:pid to update the text, media, or schedule time of a post in draft, scheduled, or failed status. Editing a failed post lets you correct content issues before calling POST /v1/posts/:pid/retry. Update the scheduled time with:

curl -X PATCH https://api.social-api.ai/v1/posts/p_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-06-02T14:00:00Z" }'

Publish a draft or scheduled post now

To publish a post that is currently in draft or scheduled status, call the publish endpoint. This sends it to all targets immediately and synchronously (the response reflects the final delivery result):

curl -X POST https://api.social-api.ai/v1/posts/p_01HZ9X3Q4R5M6N7P8V2K0W1J/publish \
  -H "Authorization: Bearer $SOCAPI_KEY"

This is the only way to publish an existing draft. PATCH only edits a post’s content, it does not trigger publishing. Consumes 1 post credit.

Cancel a scheduled post

Delete it before it publishes:

curl -X DELETE https://api.social-api.ai/v1/posts/p_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY"

Only posts in scheduled, draft, or failed status can be deleted. Once a post enters publishing, it cannot be stopped.

Status lifecycle

Every post moves through this state machine:

draft ------> scheduled --> publishing --> published
   \                   /                \-> partial
    \-----------------/                  \-> failed
   (publish_now / POST /posts/{pid}/publish)

A draft reaches publishing either by being created with publish_now: true, or later via POST /v1/posts/{pid}/publish.

Status	Meaning
`draft`	Created but not yet scheduled or published
`scheduled`	Queued for future delivery at `scheduled_at`
`publishing`	SocialAPI is actively sending the post to platforms
`published`	All targets delivered successfully
`partial`	Some targets succeeded, some failed (check per-target status)
`failed`	All targets failed

Deleting a post permanently removes it (the post returns 404 on subsequent fetch). For scheduled posts, any pending platform deliveries are marked cancelled before the post row is removed.

Platform scheduling support

When you set scheduled_at, SocialAPI holds the post in its own queue and publishes it when the scheduled time arrives. This works the same way for every platform: the post is sent to the platform only at the scheduled moment, and the platform’s own scheduler is never used. Every platform below accepts scheduled_at.

YouTube: `scheduled_at` vs `publish_at`

YouTube has its own native scheduling, which is a separate feature from scheduled_at. The two behave differently:

scheduled_at (this page): SocialAPI holds the post and uploads it to YouTube at the scheduled time. YouTube is not told about the schedule.
platform_data.youtube.publish_at: SocialAPI uploads the video to YouTube right away, and YouTube itself makes it public at the given time.

Use scheduled_at to have SocialAPI do the waiting; use publish_at to hand scheduling to YouTube. See YouTube posts for details. To discover scheduling support programmatically instead of hardcoding this table, call GET /v1/posts/validate. Each platform includes a scheduling object with a supported boolean. It is true for every publishing platform today, but querying it means your integration never relies on a hardcoded list that can silently go stale.

{
  "data": {
    "tiktok": {
      "scheduling": { "supported": true },
      "text": { "max_length": 2200, "counting_mode": "utf16" }
    }
  }
}

Posts overview for the full publishing capability matrix
Platform support for per-platform feature coverage
API Reference for the complete POST /v1/posts schema

​How scheduling works

​Managing scheduled posts

​List scheduled posts

​Edit or reschedule a post

​Publish a draft or scheduled post now

​Cancel a scheduled post

​Status lifecycle

​Platform scheduling support

​YouTube: scheduled_at vs publish_at

​Related