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

# Scheduling

> Publish now, at an exact time, or through a recurring queue.

Every post endpoint can publish immediately or at a future time. You pick the timing mode per request.

## Publish now

The default. Omit any scheduling field and the post goes out immediately.

## Schedule for an exact time

Add `scheduled_at` (ISO-8601) and an optional `timezone` (IANA name). MADIAD Hub holds the post and publishes it at that moment.

```bash theme={null}
  -F "scheduled_at=2026-06-01T15:00:00Z" \
  -F "timezone=Asia/Ho_Chi_Minh"
```

* `scheduled_at` is read as UTC when it ends in `Z`. Provide `timezone` to resolve local wall-clock times and daylight saving correctly.
* Scheduled posts return `status: "scheduled"`. They publish later — track the outcome with [webhooks](/concepts/webhooks).
* You can schedule up to one year ahead.

## Use a recurring queue

Instead of an exact timestamp, drop the post into the profile's queue with `add_to_queue=true`. It publishes in the next open slot of the profile's posting schedule.

```bash theme={null}
  -F "add_to_queue=true"
```

<Warning>
  `scheduled_at` and `add_to_queue` are **mutually exclusive** — set one or the other, never both.
</Warning>

### Configure the queue

Each profile has its own queue settings (timezone, active days, time slots). Read them:

```bash theme={null}
curl "https://api.madiad.com/v1/queue/settings?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

Update them by posting the profile id plus the fields you want to change:

```bash theme={null}
curl -X POST https://api.madiad.com/v1/queue/settings \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "timezone": "Asia/Ho_Chi_Minh", "days": ["mon","wed","fri"], "slots": ["09:00","18:00"] }'
```

## Manage scheduled posts

List a profile's pending scheduled posts:

```bash theme={null}
curl "https://api.madiad.com/v1/schedule?profile_id=$PROFILE_ID" \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

Reschedule or edit one before it publishes — pass any of `scheduled_at`, `timezone`, or `caption`:

```bash theme={null}
curl -X PATCH https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-07-01T09:00:00Z", "timezone": "Asia/Ho_Chi_Minh" }'
```

Cancel one:

```bash theme={null}
curl -X DELETE https://api.madiad.com/v1/schedule/$JOB_ID \
  -H "Authorization: Bearer $MADIAD_API_KEY"
```

The `$JOB_ID` is the `job_id` a publish call returns when `status` is `scheduled`.

<Note>
  Canceling a scheduled post does not un-count the upload recorded when you scheduled it. Since publishing is unlimited on paid plans this costs you nothing — the cancelled slot simply stays in your usage figures.
</Note>