thelastapi
Get started free

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.

On this page 8 sections

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:

PlatformText limit (characters)Media limitMedia required?
X2804No
Bluesky3004No
Threads50010No
Pinterest5001Yes
Google Business Profile1,5001No
Instagram2,20010Yes
TikTok2,20035 (photos)Yes
LinkedIn3,0009No
YouTube5,0001Yes

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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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.

Following post statuses and analytics

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

Terminal
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.

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.

To start scheduling posts, create your account at thelastapi.dev/start to access the console, or review the complete parameter schema in the Social documentation and Social posting guide.

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.