Twitter Posting API
The Twitter Posting API lets a product publish tweets, Twitter threads, Twitter polls, media posts, and Community posts through one endpoint, with scheduled posting and cross-posting to other platforms in the same workflow.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "abc123"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
It is designed for apps, platforms, automations, and AI workflows that need to publish on behalf of connected X accounts without building a separate native integration for each format.
What the Twitter Posting API does and who it is for
A unified posting endpoint is useful when the same product needs to publish a single tweet today, a thread tomorrow, and a poll or Community post next week without maintaining separate format logic for each case. The reader task is to evaluate that endpoint, map each format to its fields, and check failure conditions before sending a request. Choose a unified API when you need multiple formats, scheduled posting, and cross-posting through one workflow. Build a native X integration only when you need platform capabilities outside this posting contract and can maintain OAuth, media handling, and format changes directly.
Preserved endpoint and Tweet worked example
The preserved endpoint is POST {{API_BASE_URL}}/v1/posts. The Tweet worked example in the code examples below uses content for the tweet text, a platforms array with platform set to twitter and accountId identifying the connected account, and publishNow set to true. The example response uses HTTP 202 and returns success, status, postId, and a per-platform entry with platform, success, and platformPostUrl. Before sending, confirm the accountId belongs to the connected X account, confirm whether the post should publish now or be scheduled, and check the format-specific fields in the field map below. After sending, treat a 202 response as the starting point for status tracking and verify the per-platform success value and platformPostUrl rather than assuming every platform in a cross-post succeeded.
Field map by format: Tweet, Thread, Media, Poll, Community, Reply, Long Post, Cross-Post
For a single tweet, content carries the text and the platforms entry selects twitter and the connected account. For Twitter threads, content carries the root tweet and platformSpecificData.threadItems carries the additional tweets, each with required content of at most 280 characters and optional media. For Twitter polls, pass platforms[].platformSpecificData.poll with options containing 2 to 4 options and durationMinutes between 5 and 10080 minutes; a poll cannot be combined with media or threadItems. For Community posts, pass platforms[].platformSpecificData.communityId to post into a specific Community and use platforms[].platformSpecificData.shareWithFollowers when the post should also be shared with followers. For reply control, use platformSpecificData.replySettings with one of following, mentionedUsers, subscribers, or verified; omitting the field leaves replies open to everyone. For long posts, set platforms[].platformSpecificData.longPost to true for eligible X Premium or Premium+ accounts; the normal 280-character pre-check is skipped and X determines eligibility. For media, images, videos, and GIFs are validated against Twitter specifications before publishing, so check file type, size, and format before sending. For cross-posting, include additional platforms in the same request and expect platform-specific formatting to be handled per platform, then verify each platform result separately.
Scheduling, analytics and related capabilities
Scheduled posting queues a tweet for a later time using top-level scheduledFor as an ISO 8601 datetime and timezone as an IANA timezone, defaulting to UTC when omitted. Use scheduling when timing matters more than immediate delivery, and confirm the timezone interpretation before relying on a specific delivery minute. Related capabilities extend beyond publishing: scheduling can queue, reschedule, or cancel scheduled publishing, and analytics can retrieve performance metrics from connected X accounts for dashboards, reporting, or automated workflows. Comments and messaging capabilities use the same connected accounts when a product needs to manage replies and conversations after publishing.
Integration paths: REST, SDKs, no-code and AI/MCP
Developer stacks can use typed SDKs, predictable REST calls, or cURL against the same endpoint. No-code tools such as Zapier, Make, and n8n can trigger publishing workflows from existing automations. AI agents and MCP workflows can use a hosted MCP server, agent skills, or an OpenAI tool-calling schema to publish, schedule, and interact with social workflows. In every path, keep the same pre-send checklist: confirm accountId, confirm format fields, confirm media validity, confirm poll options and duration, confirm communityId and shareWithFollowers where relevant, confirm replySettings where relevant, and confirm scheduledFor and timezone where relevant.
Supported platforms and additional social capabilities
Beyond Twitter/X, the same API pattern covers Instagram, YouTube, Facebook, TikTok, Threads, Pinterest, LinkedIn, Bluesky, and Google Business. Additional social capabilities include a Scheduling API for queued delivery, an Analytics API for engagement and reach metrics, a Comments API for reading, replying to, hiding, and managing comments, a Messaging API for direct-message conversations, and a Comment to DM API for auto-DMing commenters by keyword with an optional public reply. Start with Twitter/X for this page, then add platforms only when the product needs them, because each additional platform adds its own formatting and result checks.
Frequently asked questions
The FAQs below answer the most common implementation questions using the preserved field names and conditions. They cover developer app requirements, threads, reply controls, long posts, link-related credit cost, and product use cases. Use them as a final check before integrating, and re-check eligibility and credit rules at implementation time because platform eligibility and pricing can change. The next step is to implement the preserved POST /v1/posts contract, run the pre-send checklist for your chosen format, and verify per-platform results after sending.
| Field | Location | Requiredness in source example | Purpose |
|---|---|---|---|
| content | Request body | Shown in Tweet example | Tweet text; root tweet for threads |
| platforms | Request body | Shown in Tweet example | Array of target platforms |
| platforms[].platform | Request body | Shown in Tweet example | Target platform; twitter for this page |
| platforms[].accountId | Request body | Shown in Tweet example | Connected account identifier |
| publishNow | Request body | Shown in Tweet example | Publish immediately when true |
| scheduledFor | Request body | Optional | ISO 8601 datetime for scheduled posts |
| timezone | Request body | Optional | IANA timezone, default UTC |
| platformSpecificData | Platform entry | Format-specific | Container for Twitter-specific fields |
| platforms[].platformSpecificData.threadItems | platforms[].platformSpecificData | Thread format | Additional tweets; each threadItems[].content required, max 280 chars |
| platforms[].platformSpecificData.replySettings | platforms[].platformSpecificData | Reply-control format | One of following, mentionedUsers, subscribers, verified; omit for everyone |
| platforms[].platformSpecificData.communityId | platforms[].platformSpecificData | Community format | Community to post into |
| platforms[].platformSpecificData.shareWithFollowers | platforms[].platformSpecificData | Community format | Also share Community post with followers |
| platforms[].platformSpecificData.longPost | platforms[].platformSpecificData | Long-post format | Set true for eligible Premium/Premium+ accounts |
| platforms[].platformSpecificData.poll.options | platforms[].platformSpecificData.poll | Poll format | Required, 2-4 options |
| platforms[].platformSpecificData.poll.durationMinutes | platforms[].platformSpecificData.poll | Poll format | Required, 5-10080 minutes; poll cannot be combined with media or threadItems |
Requiredness reflects the preserved Tweet example and source-stated format fields; do not infer types or enums beyond source.
| Failure or check | What to verify before sending | What to verify after sending |
|---|---|---|
| Media validation | Image, video, or GIF meets Twitter specifications | Per-platform success and platformPostUrl |
| Long-post eligibility | Account is eligible X Premium or Premium+; longPost set to true | X determines whether the longer post can publish |
| Link credit cost | Body contains http:// or https://; owner cost is {{OWNER_X_POST_CREDIT_COST_WITH_URL}} with a URL versus {{OWNER_X_POST_CREDIT_COST_WITHOUT_URL}} without | Credit usage for the request |
| Reply restrictions | replySettings is one of following, mentionedUsers, subscribers, verified; omit for everyone | Reply behavior on the published post |
| Poll constraints | poll.options has 2-4 items, poll.durationMinutes is 5-10080, and poll is not combined with media or threadItems | Poll appears with correct options and duration |
| Thread length | Each threadItems[].content is at most 280 characters | Thread publishes as a connected sequence |
| Scheduling | scheduledFor is ISO 8601 and timezone is IANA, default UTC | Queued delivery at the scheduled time |
| Cross-platform formatting | Each platform entry is intentional | Each platform result separately; one success does not prove all succeeded |
Checks are derived from source-stated validation, eligibility, and credit conditions; credit figures are owner tokens pending confirmation.
| Response field | Location | Meaning in Tweet example |
|---|---|---|
| success | Response body | Overall request success |
| status | Response body | Post status; published in the example |
| postId | Response body | Identifier for the created post |
| platforms[].platform | Response body | Platform that was processed |
| platforms[].success | Response body | Per-platform success |
| platforms[].platformPostUrl | Response body | URL of the published platform post |
HTTP 202 is the status shown for the Tweet example.
Frequently asked questions
Do I need to create a Twitter/X developer app?
No. The hosted connection flow handles X OAuth and token refreshes, and publishing uses the returned accountId for the connected account.
Can I publish Twitter threads through the API?
Yes. Put the root tweet in content and additional tweets in platformSpecificData.threadItems. The source documentation does not impose a hard thread-length limit.
Can I control who replies to my tweet?
Yes. Set platformSpecificData.replySettings to one of following, mentionedUsers, subscribers, or verified to narrow the audience. Leaving it out means replies stay open to everyone.
Can I publish long posts instead of a thread?
Yes, for eligible X Premium or Premium+ accounts. Set longPost: true. The normal 280-character pre-check is skipped and X determines whether the account can publish the longer post.
Why do X posts with links cost more?
Posts containing a URL are charged at {{OWNER_X_POST_CREDIT_COST_WITH_URL}} credits, compared with {{OWNER_X_POST_CREDIT_COST_WITHOUT_URL}} credits for an X post without a URL, because X charges significantly more for create requests that contain URLs. Confirm the current owner credit cost before publishing.
What kinds of products can I build with this?
Two common patterns are tools that let customers publish through their own connected accounts, and automated agents that draft and post content on a schedule.
202
{
"success": true,
"status": "published",
"postId": "post_abc123",
"platforms": [
{
"platform": "twitter",
"success": true,
"platformPostUrl": "https://twitter.com/you/status/123456"
}
]
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "abc123",
"platformSpecificData": {
"threadItems": [
{ "content": "A short example update." },
{ "content": "A short example update." }
]
}
}
],
"publishNow": true
}