Skip to content

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.

Tweet request example
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
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

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.

Input contract by field
FieldLocationRequiredness in source examplePurpose
contentRequest bodyShown in Tweet exampleTweet text; root tweet for threads
platformsRequest bodyShown in Tweet exampleArray of target platforms
platforms[].platformRequest bodyShown in Tweet exampleTarget platform; twitter for this page
platforms[].accountIdRequest bodyShown in Tweet exampleConnected account identifier
publishNowRequest bodyShown in Tweet examplePublish immediately when true
scheduledForRequest bodyOptionalISO 8601 datetime for scheduled posts
timezoneRequest bodyOptionalIANA timezone, default UTC
platformSpecificDataPlatform entryFormat-specificContainer for Twitter-specific fields
platforms[].platformSpecificData.threadItemsplatforms[].platformSpecificDataThread formatAdditional tweets; each threadItems[].content required, max 280 chars
platforms[].platformSpecificData.replySettingsplatforms[].platformSpecificDataReply-control formatOne of following, mentionedUsers, subscribers, verified; omit for everyone
platforms[].platformSpecificData.communityIdplatforms[].platformSpecificDataCommunity formatCommunity to post into
platforms[].platformSpecificData.shareWithFollowersplatforms[].platformSpecificDataCommunity formatAlso share Community post with followers
platforms[].platformSpecificData.longPostplatforms[].platformSpecificDataLong-post formatSet true for eligible Premium/Premium+ accounts
platforms[].platformSpecificData.poll.optionsplatforms[].platformSpecificData.pollPoll formatRequired, 2-4 options
platforms[].platformSpecificData.poll.durationMinutesplatforms[].platformSpecificData.pollPoll formatRequired, 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 matrix and pre-send checklist
Failure or checkWhat to verify before sendingWhat to verify after sending
Media validationImage, video, or GIF meets Twitter specificationsPer-platform success and platformPostUrl
Long-post eligibilityAccount is eligible X Premium or Premium+; longPost set to trueX determines whether the longer post can publish
Link credit costBody 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}} withoutCredit usage for the request
Reply restrictionsreplySettings is one of following, mentionedUsers, subscribers, verified; omit for everyoneReply behavior on the published post
Poll constraintspoll.options has 2-4 items, poll.durationMinutes is 5-10080, and poll is not combined with media or threadItemsPoll appears with correct options and duration
Thread lengthEach threadItems[].content is at most 280 charactersThread publishes as a connected sequence
SchedulingscheduledFor is ISO 8601 and timezone is IANA, default UTCQueued delivery at the scheduled time
Cross-platform formattingEach platform entry is intentionalEach 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 contract for the Tweet example
Response fieldLocationMeaning in Tweet example
successResponse bodyOverall request success
statusResponse bodyPost status; published in the example
postIdResponse bodyIdentifier for the created post
platforms[].platformResponse bodyPlatform that was processed
platforms[].successResponse bodyPer-platform success
platforms[].platformPostUrlResponse bodyURL 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.

Tweet response example
202

{
  "success": true,
  "status": "published",
  "postId": "post_abc123",
  "platforms": [
    {
      "platform": "twitter",
      "success": true,
      "platformPostUrl": "https://twitter.com/you/status/123456"
    }
  ]
}
Thread request builder example
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
}