# Schedule social media posts with an API

> Schedule social media posts across multiple networks using the thelastapi Social API, CLI commands, ISO timestamps, and built-in owner approvals.

**To schedule social media posts with an API, send a `POST` request to `/v1/projects/:id/social/posts` containing your text, account targets, and a future ISO 8601 timestamp in the `schedule_at` field.** You can schedule content from one minute to one year in advance across networks like X, LinkedIn, Instagram, TikTok, Facebook, and Threads using a single project key. The API manages platform formatting, character restrictions, and media attachments without requiring separate SDKs for each network.

Managing publishing across several social networks usually requires handling different authentication tokens, conflicting rate limits, and custom media upload flows. thelastapi unifies these services into a single interface. Here is how to connect accounts, upload media, schedule posts programmatically, and manage approvals for automated workflows.

## Which networks and media types can you target?

thelastapi connects to your project's accounts on twelve platforms: Instagram, Facebook, TikTok, LinkedIn, X, YouTube, Pinterest, Threads, Bluesky, Reddit, Google Business Profile, and Telegram. You can send a single post payload to up to 20 accounts simultaneously, provided each network's media and length rules are satisfied.

Each platform enforces distinct text lengths and media requirements:

| Platform | Text limit (characters) | Media limit | Media required? |
| --- | --- | --- | --- |
| X | 280 | 4 | No |
| Bluesky | 300 | 4 | No |
| Threads | 500 | 10 | No |
| Pinterest | 500 | 1 | Yes |
| Google Business Profile | 1,500 | 1 | No |
| Instagram | 2,200 | 10 | Yes |
| TikTok | 2,200 | 35 (photos) | Yes |
| LinkedIn | 3,000 | 9 | No |
| YouTube | 5,000 | 1 | Yes |

If a platform requires media, you must pass public `https://` URLs pointing to image or video files. A thelastapi AI image URL works directly, or you can host and attach your own media files.

## Step 1: Connect your social accounts

Before scheduling posts, connect your accounts to a project. thelastapi provides two environments: `development` for testing workflows in a sandbox without publishing live, and `production` for publishing to real profiles.

To connect a test account in the sandbox, pass `env=development`:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/connect?env=development" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram"}'
```

This generates a test account immediately and returns a `social_account` object with an `id`.

To connect a live account, call the endpoint in production mode (the default). The API generates a secure link valid for one hour:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/connect" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"linkedin"}'
```

From the CLI, use the `--open` flag to launch the connection link directly in your browser:

```bash
vibiz social connect linkedin --open
```

The account owner opens the URL, signs into the console, reviews the permissions, and proceeds to the platform to authenticate. Because only the project owner can complete this flow, a leaked connection link cannot attach an unauthorized account. Once connected, run `vibiz social accounts` or query `GET /v1/projects/:id/social/accounts` to retrieve your connected account IDs (prefixed with `sacc_`).

## Step 2: Upload media files

For platforms that require media, such as Instagram or YouTube, you can upload images and videos directly to your project before scheduling. Send the raw file bytes to the media endpoint:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/media?filename=announcement.jpg" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@announcement.jpg"
```

You can upload files up to 512 MB. The response returns a public `url` that you include in the `media` array of your post request. You can also pass external `https` image links directly.

## Step 3: Schedule your post via API or CLI

To schedule content, supply an ISO 8601 timestamp in the `schedule_at` field. The scheduled time must be at least one minute in the future and at most one year ahead.

Here is how to schedule a post across Instagram and X using HTTP:

```bash
curl -X POST "https://thelastapi.dev/v1/projects/prj_123/social/posts?env=production" \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Announcing our new summer menu starting next Tuesday.",
    "schedule_at": "2026-06-01T15:00:00Z",
    "media": [
      { "url": "https://example.com/summer-preview.jpg" }
    ],
    "targets": [
      {
        "account_id": "sacc_x_456"
      },
      {
        "account_id": "sacc_insta_789",
        "options": {
          "content_type": "feed",
          "first_comment": "#bakery #pastry"
        }
      }
    ],
    "confirm": true
  }'
```

You can also schedule posts directly from the terminal using the `vibiz` CLI:

```bash
vibiz social post "Announcing our new summer menu." \
  --to sacc_x_456,sacc_insta_789 \
  --media ./summer-preview.jpg \
  --at "2026-06-01T15:00:00Z" \
  --opt first_comment="#bakery"
```

Platform-specific parameters belong in the `options` object:
- **Instagram**: `content_type` (`feed`, `reel`, or `story`) and `first_comment`.
- **X and Threads**: `thread` array with follow-up posts (for example, `["Second update", "Third update"]`).
- **YouTube**: `title` (required).
- **Pinterest**: `board_id` (required).
- **TikTok**: `privacy` (`public`, `friends`, `followers`, or `private`).
- **Reddit**: `subreddit` and `title` (both required).

If any parameter violates platform rules, the API returns a `400` status listing every error path (such as `targets.0.options.title`) so you can resolve all issues in a single request.

## How approvals work for AI agents and automated keys

When building automated workflows or letting background workers prepare content, you may want a human to review the post before it goes out. thelastapi enforces permission tiers between owners and limited keys:

1. **Owner calls**: An owner key or an owner in the console can schedule posts directly by setting `"confirm": true`.
2. **Limited keys and AI agents**: When an agent or a key with Limited access creates a post in production, the post enters a `pending_approval` state. It will not publish until the project owner reviews it.

When an agent schedules a post, the API response contains a `console_url`. The owner visits this link under **Social ▸ Needs you** to approve or reject the submission. Alternatively, the owner can approve it using the CLI:

```bash
vibiz social approve pst_12345
```

Approving a post locks it into the `scheduled` status. When its scheduled timestamp arrives, the system publishes it automatically. Nothing depends on the agent running or checking back in. If the scheduled time passes while the post is still waiting for review, the owner or caller must supply a new `schedule_at` value. Learn more about human-in-the-loop agent workflows in [let an AI agent run your social media, with you approving](https://thelastapi.dev/blog/ai-agent-social-media-owner-approval).

## Following post statuses and analytics

Once created, you can track scheduled content through the API or CLI:

```bash
vibiz social posts --status scheduled
```

A post progresses through clear lifecycle states:
- `draft`: Saved without a schedule or immediate publish instruction.
- `pending_approval`: Created by an agent or limited key, awaiting owner confirmation.
- `scheduled`: Confirmed and waiting for its execution time.
- `publishing`: Currently dispatching to platform APIs.
- `published`: Successfully posted to all targeted accounts.
- `partial`: Succeeded on some accounts but encountered errors on others (details listed under `targets[].error`).
- `failed`: Failed across all targets.
- `cancelled`: Stopped before publication using `vibiz social cancel pst_12345`.

Once a post is live, you can inspect its engagement metrics. Querying `analytics` returns platform data including reach, impressions, likes, comments, shares, saves, and clicks per account. For implementation steps, read our guide on how to [read social post analytics with an API](https://thelastapi.dev/blog/social-post-analytics-api).

## Limits and pricing

Posting via the API is recorded under your account usage as `social.post` per destination account at **$0 today**. Test runs in development record nothing.

Keep these operational caps in mind when scheduling posts:
- **Batch targets**: At most 20 accounts and 35 total media files per post.
- **Scheduling range**: Between one minute and one year from the moment of creation.
- **Hourly and daily caps**: Individual platforms impose rate limits. For example, accounts are limited to 25 posts an hour, while daily maximums include 50 posts on X, 25 on Pinterest, and 100 on Instagram.

You can combine automated social scheduling with other communication tools, such as using phone alerts to notify team members when drafts need review. To explore outbound calls and messaging, see how to [give an AI agent a phone number: texts, calls and a voice agent](https://thelastapi.dev/blog/give-ai-agent-phone-number).

To start scheduling posts, create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to access the console, or review the complete parameter schema in the [Social documentation](https://thelastapi.dev/docs/social) and [Social posting guide](https://thelastapi.dev/docs/guides/social).

## Frequently asked questions

### What format should I use for the schedule_at parameter?

Pass a standard ISO 8601 string, such as 2026-06-01T15:00:00Z. The timestamp must be at least one minute in the future and at most one year ahead.

### What happens if an approval is delayed past the scheduled post time?

If a post sits in pending_approval past its original schedule_at timestamp, it will not publish immediately upon approval. You must provide a new schedule_at timestamp to reschedule it.

### How much does it cost to schedule social media posts?

Posting and scheduling are billed at $0 today on thelastapi. Platform usage is logged as social.post per account, while sandbox actions in development record nothing.

### Can an AI agent publish directly to my production accounts without confirmation?

No. Calls from limited access keys or AI agents in production automatically receive the status pending_approval. The post only runs after a project owner confirms it in the console or CLI.

---

Published 2026-11-15 · https://thelastapi.dev/blog/schedule-social-posts-api
