Skip to main content
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": "post_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"

​
Reschedule a post

Update the scheduled time with PATCH: 
curl -X PATCH https://api.social-api.ai/v1/posts/post_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/post_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/post_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY"
Only posts in scheduled or draft status can be cancelled. 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.
StatusMeaning
draftCreated but not yet scheduled or published
scheduledQueued for future delivery at scheduled_at
publishingSocialAPI is actively sending the post to platforms
publishedAll targets delivered successfully
partialSome targets succeeded, some failed (check per-target status)
failedAll targets failed
A post can also be set to cancelled by deleting it while it is in draft or scheduled status.

​
Platform scheduling support

Not all platforms support deferred publishing through their APIs. For platforms that do not support scheduling natively, SocialAPI holds the post server-side and publishes it at the scheduled time.
PlatformNative schedulingMedia typesNotes
InstagramYesImage, Video (Reel), Carousel (2-10)Min 10 min in future, max 75 days
FacebookYesImage, VideoMin 10 min in future
ThreadsYesImage, Video, CarouselMin 10 min in future
LinkedInYesImage, Video, CarouselMin 10 min in future
GoogleNo (server-side)ImageSocialAPI holds and publishes at scheduled time
TikTokNo (server-side)Video, Photo carousel (2-35)SocialAPI holds and publishes at scheduled time
YouTubeComing soonVideoNot yet available
X / TwitterComing soon-Not yet available