Schedule tweets with an API

X's API creates posts immediately; there is no future publish time on POST /2/tweets. A scheduler stores the post and calls X at the right moment. With us, that's one field: add scheduled_at to the request and we store the post with status scheduled.

Our delivery worker runs every minute. When the time comes, it checks the X account is still connected, refreshes the OAuth token if it's close to expiring, uploads any images, creates the post on X and reads it back to confirm it exists. The result goes to your webhook and to GET /v1/posts/:id.

If X is unavailable or rate-limits the request, the attempt is retried after 30s, 2m, 10m, 30m and 2h. After six attempts the target is failed with the last error. A post scheduled for 09:00 during an X outage can therefore go out late; check attempts and published_at on the target to see when it actually went out.

This schedules one X post with a link for 9:00 New York time. The text is 131 characters as JavaScript counts them but 120 weighted characters as X counts them, because the 34-character URL counts as 23.

curl https://socialsforai.com/v1/posts \
  -H "Authorization: Bearer $SOCIALS_API_KEY" \
  -H "Idempotency-Key: launch-v2-4-x" \
  -d '{
    "accounts": ["acc_x_company"],
    "text": "v2.4 is out: cancel scheduled posts from the API, 24h webhook retries, custom Bluesky PDS hosts. https://example.com/changelog/v2-4",
    "scheduled_at": "2026-11-10T09:00:00-05:00"
  }'

A 201 with status: "scheduled" and the time normalized to UTC (trimmed here to the relevant fields). Because the text contains a link, the response also carries an x_link_cost warning. It doesn't block the post; it tells you this post will be billed by X at the with-URL rate, $0.200 instead of $0.015.

{
  "id": "post_c8Wq1NfZ4yHs6TbA",
  "object": "post",
  "status": "scheduled",
  "scheduled_at": "2026-11-10T14:00:00.000Z",
  "targets": [
    {
      "id": "tgt_P0xEo7Jr2mLa9VuK",
      "account_id": "acc_x_company",
      "platform": "x",
      "status": "pending",
      "attempts": 0,
      "next_attempt_at": "2026-11-10T14:00:00.000Z",
      "url": null,
      "error": null
    }
  ],
  "warnings": [
    {
      "account_id": "acc_x_company",
      "platform": "x",
      "severity": "warning",
      "code": "x_link_cost",
      "message": "Posts with a URL cost $0.200 through the X API instead of $0.015 (docs.x.com pricing).",
      "fix": "Remove the link, or send a link-free version for X in platform_options.x.text. A link in a reply is also billed at the with-URL rate."
    }
  ]
}

Send one request per post, each with its own scheduled_at and idempotency key. Here is a week of daily posts from a Python list. If the script dies halfway and you rerun it, the keys make the already-created posts come back as replays instead of duplicates.

Two limits shape batch loads. The fair-use cap of 100 posts per X account counts posts created for that account in the last 24 hours, scheduled ones included, so loading a month of hourly posts in one go stops at 100 with daily_cap_reached; load a few days at a time. And on the Free plan, every created post counts toward the 100-posts-a-month limit when it's created.

import os, requests
from datetime import datetime, timedelta, timezone

API = "https://socialsforai.com"
headers = {"Authorization": f"Bearer {os.environ['SOCIALS_API_KEY']}"}
start = datetime(2026, 11, 10, 14, 0, tzinfo=timezone.utc)

for day, text in enumerate(daily_tips):  # 7 different strings
    when = (start + timedelta(days=day)).isoformat()
    r = requests.post(f"{API}/v1/posts",
        headers={**headers, "Idempotency-Key": f"tips-{when}"},
        json={"accounts": ["acc_x_company"], "text": text, "scheduled_at": when})
    if r.status_code == 422:
        for issue in r.json()["error"]["issues"]:
            print(day, issue["code"], issue["fix"])
    else:
        r.raise_for_status()

Most scheduling bugs are about time zones, duplicates and counting.

• Timestamps without a time zone. 2026-11-10T09:00:00 is rejected with a 400 validation_error. Add Z for UTC or an offset like -05:00.
• Times slightly in the past. A scheduled_at up to 5 minutes ago publishes immediately; more than 5 minutes ago fails with scheduled_in_past. Clock skew on your server is the usual cause.
• Recycled text. Two posts with identical text for the same account, created within 24 hours of each other, fail with duplicate_content, even if they're scheduled a week apart.
• Counting with len() or .length. X weights characters. Check with the X character counter or dry_run, and read how the weights work on the X character limit page.
• Editing by resending. There is no edit. Cancel and recreate with a new idempotency key; the old key with a new body returns 409 idempotency_key_reused.

Call GET /v1/posts/:id and read the target's status, attempts, next_attempt_at and error. The error.code tells you what happened.

• Status pending with attempts above 0 and a next_attempt_at: a retryable failure (platform_rate_limited, platform_unavailable). It's waiting for the next retry; do nothing.
• account_needs_reauth: X refused the token and it couldn't be refreshed. Send the account owner a new connect link, then recreate the post.
• duplicate_content from X: X itself rejected the text as a duplicate. Change the text and create a new post.
• platform_rejected: X refused the post for another reason; its response is in the message.
• Status canceled: someone called DELETE /v1/posts/:id. Nothing was sent to X and nothing was charged.

If a person schedules their own posts by hand, yes. X's own scheduling tools show the post as it will look, with no API work. Paying for an API makes no sense for that workflow.

An API is the better fit when software decides what goes out: a product that posts for its users, a pipeline that announces releases, a Twitter bot, or an agent using our X MCP server. It's also the only way to schedule the same announcement to X, Bluesky and LinkedIn in one call; see crossposting. X's per-post fees still apply; see X API pricing.