How to make a Twitter (X) bot

You need four things: an X account for the bot, permission to post as it, code that decides what to post, and something that runs that code on time.

Permission is the hard part. Posting as an account through X's API v2 means an OAuth 2.0 flow with PKCE, token storage, and refreshing tokens before they expire, or the bot stops working. Our X connector requests the scopes tweet.read tweet.write users.read media.write offline.access, stores the tokens encrypted (AES-256-GCM) and refreshes them automatically, so your code only ever sees an account id.

The code that decides what to post can be anything: a script that reads an RSS feed, a build pipeline that announces releases, or an AI agent. If the agent runs in Claude Code or Cursor, our X MCP server gives it a create_post tool and you write no HTTP code at all. For no-code workflows, see n8n.

X bills API usage per request. Its developer pricing page lists Post: Create at $0.015 per request and Post: Create with a URL at $0.200 per request, with no subscription or minimum spend. A bot that posts links pays about 13 times more per post than one that doesn't.

The table below is that math over a 30-day month. It covers X's fees only. On our side, the Free plan includes 100 posts a month and 3 active accounts, which covers a bot posting three times a day; see pricing for the paid plans and the X credit they include. Our X API pricing page has the full breakdown.

One more line item: X charges $0.005 per post returned by a read. We read each X post back once after publishing to confirm it exists, and if your bot reads mentions or timelines, those reads are billed by X at the same rate.

Here is the full round trip for a bot that announces passing builds. First the request. The Idempotency-Key is the build number, so if your CI job retries the step, the second call returns the first post instead of creating another.

curl https://socialsforai.vercel.app/v1/posts \
  -H "Authorization: Bearer $SOCIALS_API_KEY" \
  -H "Idempotency-Key: build-1482" \
  -d '{
    "accounts": ["acc_x_bot"],
    "text": "Build 1482 passed. 412 tests, 0 failures. Deploying to production now.",
    "wait": true
  }'

With wait: true the call returns after X has answered. The post is published, the target has X's post id and URL, and verified is true because we read the post back. The text is 70 weighted characters, well under 280, and has no link, so X's fee for it is $0.015.

If the same request is sent again with the same key, you get this same body back with the header Idempotent-Replayed: true. Reusing the key with different text returns 409 idempotency_key_reused.

{
  "id": "post_Qm3v9XcR1aZ0bL7e",
  "object": "post",
  "status": "published",
  "text": "Build 1482 passed. 412 tests, 0 failures. Deploying to production now.",
  "media": [],
  "platform_options": {},
  "scheduled_at": null,
  "created_at": "2026-11-01T15:02:11.204Z",
  "completed_at": "2026-11-01T15:02:12.918Z",
  "metadata": {},
  "targets": [
    {
      "id": "tgt_k2Hs8PZq0nV4wYcT",
      "account_id": "acc_x_bot",
      "platform": "x",
      "status": "published",
      "url": "https://x.com/buildbot/status/1852039912345678901",
      "external_post_id": "1852039912345678901",
      "attempts": 1,
      "next_attempt_at": null,
      "published_at": "2026-11-01T15:02:12.611Z",
      "verified": true,
      "error": null
    }
  ]
}

The same call in TypeScript with fetch, run from a cron job, a serverless function or a CI step. It throws on any non-2xx status so your scheduler marks the run as failed and you see the error code in the logs.

const res = await fetch("https://socialsforai.vercel.app/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOCIALS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `build-${buildNumber}`,
  },
  body: JSON.stringify({
    accounts: [process.env.X_BOT_ACCOUNT_ID],
    text: `Build ${buildNumber} passed. ${tests} tests, 0 failures.`,
    wait: true,
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.fix ?? body.error.message}`);
console.log(body.targets[0].url);

The Python version with requests. On a 422 it prints each preflight issue's code and fix, which is usually all you need to correct a template.

import os, requests

API = "https://socialsforai.vercel.app"
r = requests.post(f"{API}/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['SOCIALS_API_KEY']}",
             "Idempotency-Key": f"build-{build_number}"},
    json={"accounts": [os.environ["X_BOT_ACCOUNT_ID"]],
          "text": f"Build {build_number} passed. {tests} tests, 0 failures.",
          "wait": True})
if r.status_code == 422:
    for issue in r.json()["error"]["issues"]:
        print(issue["code"], "->", issue.get("fix"))
r.raise_for_status()
print(r.json()["targets"][0]["url"])

Repeating yourself and posting in bursts are the two patterns that get automated accounts in trouble, and both are checked before anything reaches X.

• Duplicate text. If the same account already has the same text published or queued in the last 24 hours, preflight returns duplicate_content. Add a variable part (a build number, a date, a count) to every template.
• Bursts. X's rate-limit docs list POST /2/tweets at 100 requests per 15 minutes per user and 10,000 per 24 hours per app. Our fair-use cap is stricter: 100 posts per X account per rolling 24 hours, returned as daily_cap_reached. Spread posts out with scheduled_at instead of firing them together.
• Links in every post. Each one costs $0.200 at X's rates, and our preflight attaches an x_link_cost warning (it doesn't block). Moving the link into a reply doesn't lower the bill: the reply is itself a post with a URL, so the pair costs $0.215. If cost matters, post without the link or give X its own link-free text in platform_options.x.text.
• X's own automation rules. X publishes rules for automated accounts in its Help Center. Read the current version before launch; we don't paraphrase them here because they change.

These are the common failures, with the fix for each.

• Counting characters with text.length. X counts URLs as 23, emoji as 2 and CJK characters as 2. A 260-character JavaScript string can be over the limit. Use our X character counter or dry_run, which apply X's weights. Details on the X character limit page.
• Posting the same template every hour. The second identical post within 24 hours fails with duplicate_content.
• Retrying without an idempotency key. A timeout on your side doesn't mean the post failed. Without a key, the retry can publish a second copy.
• Scheduling with a local timestamp. scheduled_at must include Z or an offset like -05:00; 2026-11-10T14:00:00 without one is rejected with a 400 validation_error.
• Sending video. We don't post video to any network yet; preflight returns video_not_supported. Images work: up to 4 per X post, 5 MB each.

Every error carries a stable code, a message and a fix. Preflight errors come back as a 422 preflight_failed with an issues array, and nothing is published. Errors from X itself land on the target after publishing starts.

• text_too_long: the message gives the weighted count, for example "Text is 283 characters; X allows 280." Shorten it, or set platform_options.x.text to a shorter version.
• duplicate_content: same text on the same account within 24 hours. Vary the text.
• daily_cap_reached: 100 posts on this account in 24 hours. Schedule the rest later.
• account_needs_reauth: the token couldn't be refreshed. Create a new connect link for the bot account and approve it again. An account.needs_reauth webhook fires when this happens.
• platform_rate_limited or platform_unavailable: X returned 429 or a 5xx. These retry on their own after 30s, 2m, 10m, 30m and 2h (6 attempts), then the target is failed.
• platform_rejected: X refused the post for another reason. The message includes X's response; adjust the post and send it with a new idempotency key.