X API: How to Post a Tweet with POST /2/tweets

To post a tweet with the X API, you send POST https://api.x.com/2/tweets with a JSON body containing text, authorized as the user you're posting for. That takes a user access token: OAuth 2.0 with the tweet.read, tweet.write, and users.read scopes, or OAuth 1.0a. X bills each call, $0.015 per post and $0.20 per post with a link.

Getting the developer app and tokens is covered in our X API access guide, and the full price list is in X API pricing. This post covers the posting call itself: the request, the media upload, threads, the body fields, and the errors. Every X fact links to X's developer docs, fetched 2026-10-19.

What do you need before you start?#

• An X developer app from the Developer Console, with OAuth 2.0 turned on if you'll use it.
• Credits in your balance. X is pay-per-use, so requests are blocked when the balance runs out.
• A user access token for the account you're posting as. The app-only Bearer Token can't create posts.
• The media.write scope too, if you'll attach images or video.

Which X API keys do I need for posting?#

It depends on the auth method. X's Manage Posts guide accepts two kinds of user context for POST /2/tweets:

For your own account, the Access Token and Secret the console generates are enough. For other people's accounts, each user goes through the OAuth flow, which X API access walks through step by step.

Step 1: Post a text tweet#

Send the text as JSON with the user's token.

curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Shipping notes for v2.4 are up."}'

A success is 201 Created with the new post's ID, per the Create Post reference:

{
  "data": {
    "id": "1840000000000000000",
    "text": "Shipping notes for v2.4 are up.",
    "edit_history_post_ids": ["1840000000000000000"]
  }
}

Store data.id. You need it to reply, build a thread, or delete the post later.

Count characters the way X does. X's character counting guide allows 280 characters, but every URL counts as 23, every emoji as 2, and Chinese, Japanese, and Korean characters as 2 each, so the CJK limit is effectively 140.

Step 2: Upload media and attach it#

Upload first, then pass the media ID in media.media_ids. A post takes up to 4 images, 1 GIF, or 1 video.

For an image, one request to POST /2/media/upload does it. Send the file as base64 in JSON or as raw bytes in multipart, with a media_category:

curl -X POST "https://api.x.com/2/media/upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "media=@chart.png" \
  -F "media_category=tweet_image"

The response's data.id is the media ID. Then post with it:

curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Signups by week", "media": {"media_ids": ["<MEDIA_ID>"]}}'

Video and large GIFs use the chunked flow, from X's chunked upload guide:

1. Initialize. POST /2/media/upload/initialize with media_type, total_bytes, and media_category (tweet_video or tweet_gif). It returns the media ID.
2. Append. POST /2/media/upload/{id}/append once per chunk, with segment_index starting at 0. X recommends chunks of 5 MB or less; 8 MB is the maximum.
3. Finalize. POST /2/media/upload/{id}/finalize. If the response has processing_info, the video is still processing.
4. Poll status. GET /2/media/upload with command=STATUS and the media_id, waiting check_after_secs between calls, until the state is succeeded.

The video cap belongs to the posting user, not your developer plan. A video over that user's limit uploads fine and then fails at POST /2/tweets with 403 Forbidden.

Step 3: Reply and build a thread#

A thread is a chain of replies. Post the first tweet, then reply to its ID, then reply to the reply:

curl -X POST "https://api.x.com/2/tweets" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "2/ The biggest change is the new export.", "reply": {"in_reply_to_tweet_id": "1840000000000000000"}}'

Plan for these:

• Replies to other people need a summons on self-serve. X's Manage Posts guide says a reply is only allowed "if the replying account has been explicitly summoned by the original post's author," by an @mention or a quote. Enterprise isn't subject to the rule.
• Threads aren't atomic. If the fourth post fails, the first three are already live. Save each ID as you go so you can resume from the last one.

What else can the POST /2/tweets body do?#

Polls, reply controls, disclosures, communities, and edits. The fields from the Create Post reference that most products use:

One cashtag per post on self-serve. X rejects a post with more than one $TICKER.

How much does each X API post cost?#

Each successful create is billed from your credit balance. From X's pricing page, fetched 2026-10-19:

Links are the expensive part. A post with a URL costs about 13 times a plain post, and each post in a thread is billed separately, so a 5-post thread with one link costs $0.26. X's page doesn't define what counts as a URL. Adeli's records count a bare domain such as example.com as a link (X API pricing docs), so treat anything that looks like a domain as one. Scenarios at SaaS scale are in our X API pricing breakdown.

What are the rate limits for posting to X?#

100 posts per 15 minutes per user and 10,000 per 24 hours per app, per X's rate limits page:

X's own docs disagree. The Manage Posts guide lists 200 posts per 15 minutes per user and 300 per 3 hours. Read the x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset headers on every response instead of hard-coding either number. A 429 with error code 88 means you've hit the limit; wait until the reset time.

How do you know it worked?#

A 201 with data.id means the post is live. The failures you'll see most:

Sources: Manage Posts guide and rate limits.

X also refuses duplicates. Posting the same text the account published recently gets rejected, so vary the text of automated posts.

To delete a post, send DELETE https://api.x.com/2/tweets/{id} with the author's token. X's Manage Posts quickstart says you can only delete posts you authored, and the delete is billed.

Is there a faster way to post to X via API?#

Yes, if your users are the ones posting. Posting directly means an X developer app, the OAuth flow, a refresh job for every account, the media upload steps, and resuming broken threads yourself.

Adeli's X API maintains the X developer app, has passed X's review, and refreshes every connected account's tokens, so you hold one API key. A post with a thread is one request to POST /api/v1/posts:

curl -X POST "https://app.tryadeli.com/api/v1/posts" \
  -H "Authorization: Bearer $ADELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "x",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "text": "Herons fish at dawn. A thread:",
    "thread": [{ "text": "They stand still for minutes at a time." }]
  }'

How Adeli maps to the X steps above:

• No separate upload step. Send media inline as { content_type, base64 }, or a video as a public HTTPS { url }: up to 4 images, 1 GIF, or 1 video. Adeli caps X images at 5 MB, GIFs at 15 MB, and video at 512 MB.
• Threads of up to 24 more posts. X publishes synchronously, so 201 is the finished post. If a later post fails, you get 207 with status: "partial", the failed post's error, and not_attempted for the rest, so you know exactly where to resume.
• Duplicates come back as 409 duplicate_post, and the 280-character limit is counted the way X counts it, with every link as 23.
• Deleting is DELETE /api/v1/posts/x/{postId} with the post's providerId.
• X's fees are passed through at X's published rates, with no markup. X needs a card on file, so until your workspace has one, publishing returns 402 x_billing_required. GET /api/v1/usage/x reports the month's running total.

The same posting API publishes to Instagram, TikTok, YouTube, Facebook, and Bluesky. One X account is one connected account on Adeli's pricing, and your first 3 connected accounts are free.