---
title: "X (Twitter) API"
description: "Ayrshare's Twitter API (X API): publish posts, threads, and polls, send DMs, search X by keyword, and monetize video through one REST API for 14+ networks."
canonical: https://www.ayrshare.com/x-twitter-api/
lastModified: 2026-11-03
pageType: ai-agent
---

# X (Twitter) API

> Ayrshare's Twitter API (X API): publish posts, threads, and polls, send DMs, search X by keyword, and monetize video through one REST API for 14+ networks.

## X (Twitter) API for Publishing, Social Listening, and Monetization

Ayrshare's API for X (formerly Twitter) enables developers to publish posts, threads, images, videos, and polls via a single REST endpoint. The integration handles scheduling, direct messages, keyword search, social listening, analytics, and monetization.

Your users link their X accounts through an OAuth flow inside your product on your own X developer app, while Ayrshare manages media uploads, threads, Premium checks, and X's ongoing API changes.

[Read the X (Twitter) Docs](/docs/apis/post/social-networks/x-twitter)
[Get Your API Key](/pricing/)

- **>99.99%** — API uptime
- **30M+** — API calls per day
- **14+** — Social media networks
- **AI-Native** — Native MCP server for any AI agent

## What Do You Need to Use the X (Twitter) API?

X sells API access by the request. You sign up in the X Developer Console, create an app, set its permissions, and buy credits before your first call goes through. There's no review queue, but every post, read, and direct message draws down your balance. Each account you post for also needs its own OAuth token.

With Ayrshare, you still bring your own X app and credits, but you skip the OAuth flow, media uploads, and error handling, and you get the parts of X that not all social media APIs can offer: direct messages, keyword search, and video monetization. Read why bring-your-own-app matters in [Is Your Social Media API Compliant with X's Developer Policies?](/blog/x-api-compliance-byo-app/)

- **Access**: An X Developer Console account, an app with user authentication set up, and OAuth tokens for each account. No app review, but X's developer policies apply.
- **Video monetization**: Eligible publishers tag video for X's Amplify pre-roll ads or sponsorship programs in the publish call itself, with no detour through Media Studio. [Read how it works](/blog/monetize-x-video-with-ayrshare/), then [ask us to enable it](mailto:support@ayrshare.com).
- **Direct messages**: Read and send X direct messages for every linked account, with conversation history and auto-responses, through the [Messaging API](/social-media-messenger-apis/). Your X app just needs the direct message permission.
- **Listening**: Search X for keywords and hashtags with advanced operators, and look up any public account's followers and profile, with [keyword search](/docs/apis/listen/keyword/search-tweets) on your own X credits.

## Sponsored X Video for the 2026 FIFA World Cup

A broadcaster needed a reliable partner for the biggest event in the world, the 2026 FIFA World Cup. Ayrshare worked with X so the broadcaster could publish, geo-fence, and sponsor clips through the API, with ad creative matched to each clip instantly, all inside a white-label integration.

- **250M+ (Video views and counting)**: Sponsored clips published through the API during the tournament, with creative matched to each clip the moment it went live.
- **15 seconds (Down from 15 minutes)**: Processing time per clip, a massive reduction for live-event workflows on the world's biggest stage.
- **1,000s (Clips posted, no issues)**: Every clip geo-fenced and sponsored via a white-label integration, without a single publishing issue.

## Post and Schedule to X (Twitter) in Your Language

Each sample publishes a post with an image now, then schedules a video for later. Same endpoint, same JSON, in Node.js, Python, PHP, Java, Go, Ruby, C#, or plain cURL. Every request that targets X also carries two headers, X-Twitter-OAuth1-Api-Key and X-Twitter-OAuth1-Api-Secret, with your own X developer app's credentials, as the [X BYO keys setup guide](/docs/dashboard/connect-social-accounts/x-twitter-byo-keys) explains. Add a Profile-Key header to post for one of your users.

[Full Post API Reference](/docs/apis/post/overview)

- **cURL**
- **Node.js**
- **Python**
- **PHP**
- **Java**
- **Go**
- **Ruby**
- **C#**

## X (Twitter) API Limits: Post Types, Media, and Characters

X's rules in one place. The full list lives in the [X media guidelines](/docs/media-guidelines/x_twitter) and the [X publishing options](/docs/apis/post/social-networks/x-twitter).

- **7 post types (Post types)**: Text, links with an automatic preview, images, video, animated GIFs, polls, and threads.
- **1 X app for every profile (Accounts)**: Any X account, linked through OAuth on your own X developer app. One app per Ayrshare account covers every user profile you link.
- **4 images per post (Images)**: JPG, PNG, GIF, or WEBP, up to 5 MB and 8192 x 8192 px. 1200 x 675 px suits a single image.
- **512 MB per video (Video)**: MP4 or MOV, up to 140 seconds, at 60 FPS or less, with an aspect ratio between 1:3 and 3:1. Accounts X has approved for longer uploads, such as Premium accounts, can post video up to 4 hours with longVideo.
- **280 characters per post (Characters)**: Premium accounts can post up to 25,000 characters, and Ayrshare allows it automatically. Alt text runs to 1,000 characters per image.
- **Auto thread splitting (Threads)**: Set thread to true and Ayrshare splits text over 280 characters into connected posts, keeping sentences whole.
- **4 reply settings (Polls and reply settings)**: Attach a poll with a duration and options, and limit who can reply.
- **300 API calls per 5 min per profile (Scheduling and limits)**: Pass a scheduleDate to publish later. Ayrshare sets no X posting cap of its own, so your X app's rate limits and credits decide volume.

## What Else Can You Do With the X (Twitter) API?

- **Split long text into a numbered thread**: Separate posts with blank lines, or let Ayrshare split long text. threadNumber appends 1/3, 2/3, and 3/3, and each entry in twitterOptions.mediaUrls attaches to one post in order, with null to skip one. More in [How to Schedule Twitter Threads with the Twitter API](/blog/how-to-schedule-twitter-threads-with-the-twitter-api/).
- **Quote a post and limit who can reply**: Quote any post by its X post ID, which you can read from the /post response, the history endpoint, or the post URL. Add replySettings to limit who can reply.
- **Attach a poll and choose who can reply**: Send the poll options and how many minutes it stays open. replySettings takes following, mentioned, subscribers, or verified.
- **Upload up to 4 hours of video**: For accounts X has approved for longer uploads, set longVideo and attach up to 4 hours of video, with a thumbnail, a title, and SRT subtitles. Long video needs an Ayrshare Business or Enterprise plan.
- **Add alt text, country limits, and AI labels**: Alt text maps to images in order, up to 1,000 characters each. Block or allow countries for the media, and apply X's Made with AI label with isAIGenerated, which can't be changed after publishing.

## Why Use Ayrshare Instead of the X (Twitter) API Directly?

Your product sends one request with your X app's key and secret in two headers and gets back the X post ID and URL. Ayrshare runs the account linking flow, uploads the media, splits threads, and checks Premium entitlements. When X answers with a 402 for empty credits, a 403 for a missing permission or a [duplicate post](/solutions/x-twitter-api-error-403-duplicate-post-how-to-fix-it/), or a 429 for a rate limit, you get a clear error back. When X changes the API, the fix ships on our side, not in your sprint.

For a step-by-step walkthrough, read [How to Post to Twitter (X) with an API](/blog/twitter-api-how-to-post-and-get-analytics-with-the-twitter-api/).

[See the X Publishing Options](/docs/apis/post/social-networks/x-twitter)

- **One simple endpoint**: Send one POST request with your post, media URLs, and the user's Profile-Key, plus your X app's key and secret in two headers.
- **We deal with X**: Account linking, media upload, thread splitting, and Premium checks. Ayrshare doesn't store your keys, apart from an encrypted copy while a linking session is open.
- **One link, the whole lifecycle**: Get the X post ID and URL right away. The same account link then powers analytics, replies, direct messages, keyword search, and, for eligible publishers, amplify video monetization. No second integration to build.

## Beyond Posting: The Rest of the X (Twitter) Lifecycle

Replies, direct messages, history, and analytics run through the same account link and credential headers as posting, and draw on the same X credits.

Not available on X: reviews and boosted ads. See every network you can reach with the same integration on the [supported networks page](/supported-networks/).

- **Analytics**: Likes, replies, reposts, bookmarks, and impressions per post, plus non-public metrics for posts under 30 days old. Account analytics include followers and Premium status.
  - [Analytics API](/social-media-analytics-api/)
- **Comments**: Read replies to a post, reply, and delete your replies.
  - [Engagement API](/social-media-engagement-api/)
- **Messages**: Read and send X direct messages for each linked account, with auto-responses. Your X app needs the direct message permission.
  - [Messaging API](/social-media-messenger-apis/)
- **History**: Pull an account's past posts with analytics, including posts made outside Ayrshare.
  - [History API](/history-api/)
- **Pre-publish checks**: Scheduled X posts are checked for media requirements on submit, so a bad video URL fails early.
  - [Validate docs](/docs/apis/validate/overview)

## FAQs About the X (Twitter) API

### Can I post to X (Twitter) through an API?

Yes, you can post to X (Twitter) through an API. Ayrshare's API for X enables developers to publish posts, threads, images, videos, and polls via a single REST endpoint. The integration handles scheduling, direct messages, keyword search, social listening, analytics, and monetization. Start with the [X publishing options](/docs/apis/post/social-networks/x-twitter).
### Is the X (Twitter) API free?

The X (Twitter) API isn't free. X bills every request from prepaid credits, with no free tier for posting, and the minimum credit purchase is $5. Through Ayrshare you still use your own X app and credits, but Ayrshare's plan covers the linking, media, threads, and the other 14+ networks on the same call. [Compare Ayrshare plans](/pricing/).
### How do I get a Twitter API key?

To get a Twitter API key, sign in to the X Developer Console, create an app in the Production environment, set its permissions to read, write, and direct message, and buy credits. The app's API key and secret are what you send to Ayrshare. The [X BYO keys setup guide](/docs/dashboard/connect-social-accounts/x-twitter-byo-keys) walks through each screen, including the callback URLs.
### How do I post to X with an API?

To post to X with an API, link the X account once, then send a POST /post request with "platforms": ["twitter"], your post text, any media URLs, and your X app's key and secret in two headers. Add scheduleDate to publish later. The tutorial [How to Post to Twitter (X) with an API](/blog/twitter-api-how-to-post-and-get-analytics-with-the-twitter-api/) covers the first request and reading analytics back.
### What does the Twitter API allow?

The Twitter API allows posting text, images, video, polls, threads, and quote posts, reading posts and metrics, replying, sending direct messages, and searching posts by keyword. Premium accounts add long posts, approved accounts add long video, and eligible publishers can monetize video through Amplify. Through Ayrshare, all of it runs on your own X app and credits. If a call fails on permissions, see [X API 403 access tier and scopes](/solutions/twitter-x-error-403-forbidden-tier-access-scopes/).
### How much does the X API cost per post?

The X API costs $0.015 per post on pay-per-use pricing, and $0.20 for a post that contains a link. Reading posts costs $0.005 each, and reading your own account's data costs less. X sets a monthly cap of 3 million post reads before Enterprise. Ayrshare's fee is separate and covers every network, so check [Ayrshare's plans](/pricing/) alongside your X credit budget.

## Your Users Are on X (Twitter). Your Product Can Be Too.

Get an API key, link an X account with your own X app credentials, publish your first post, and turn on the other networks with the same call when you need them.

[Get Your API Key](/pricing/)
[Read the X (Twitter) Docs](/docs/apis/post/social-networks/x-twitter)