> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling posts

> Schedule posts across platforms via the unified social media API. One call, multiple targets, one scheduled time.

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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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):

```bash theme={null}
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:

```bash theme={null}
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](/posts/youtube) for details.

To discover scheduling support programmatically instead of hardcoding this table, call [`GET /v1/posts/validate`](/api-reference/posts/get-platform-constraints). 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.

```json theme={null}
{
  "data": {
    "tiktok": {
      "scheduling": { "supported": true },
      "text": { "max_length": 2200, "counting_mode": "utf16" }
    }
  }
}
```

## Related

* [Posts overview](/posts/overview) for the full publishing capability matrix
* [Platform support](/guides/platforms) for per-platform feature coverage
* [API Reference](/api-reference/introduction) for the complete `POST /v1/posts` schema