# OmniSocials X API > Publish posts, threads and polls to X. Answer DMs and read what every post did. One API key, on OmniSocials’ own X app. This is the machine-readable version of [omnisocials.com/x-api](https://omnisocials.com/x-api), maintained for AI agents. Facts checked against the OmniSocials app and API on October 17, 2026. Platform reference: [docs.omnisocials.com/platforms/x](https://docs.omnisocials.com/platforms/x). API reference: [docs.omnisocials.com/api](https://docs.omnisocials.com/api). ## Basics - Base URL: `https://api.omnisocials.com/v1` - Auth: `Authorization: Bearer omsk_live_...`. One key belongs to one workspace. Keys are created in the app under Settings, API. - Channel id in `accounts`: `x`. The account connects inside the OmniSocials app, not through the API. - Rate limit: 100 requests per minute per key. A 429 carries `Retry-After`. - Responses use a `{ "data": ... }` envelope. Create returns `201`. - Webhooks: `post.scheduled`, `post.published`, `post.failed`, `post.approved`, `post.rejected`, signed with HMAC-SHA256 in `X-OmniSocials-Signature`. ## Skip the X developer app X’s own API needs a developer app, pay-per-use billing on every call, OAuth with two-hour tokens and a chunked media upload. OmniSocials already did that work. - On your own: X app, Billing, OAuth, Tokens, Uploads, Polling, Char count, Threads, then the first post. - Permissions your own app must get approved: `tweet.read`, `tweet.write`, `users.read`, `media.write`, `offline.access`, `dm.read`, `dm.write`. - On OmniSocials: sign in, create an API key, POST. One sign-in grants all 7 scopes. ## Schedule a post ```bash curl -X POST https://api.omnisocials.com/v1/posts/create \ -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "Post from your own code: SDKs in 8 languages.", "accounts": ["x"], "media_urls": [ { "url": "https://cdn.example.com/sdk.png", "alt": "SDK code" } ], "x": { "reply_settings": "following" }, "schedule_at": "2026-10-22T18:00:00Z" }' ``` The answer (`201`, shortened): ```json { "data": { "id": "1024", "status": "scheduled", "app_url": "https://app.omnisocials.com/create-post/1024" } } ``` ## Posts, threads and polls, one request Every X format shares one request shape. Add media with alt text, split a long text into a thread or ask a question with a poll. OmniSocials counts characters the way X does before anything is sent. - **Posts and long posts.** Up to 4 images or one video, each image with alt text. Basic and Premium accounts post up to 25,000 characters, counted the way X counts. (`media_urls`, `alt`) - **Threads.** 2 to 25 tweets in one request, each with its own text and media. OmniSocials posts them in order as one thread. (`x.thread_parts`) - **Polls, replies and labels.** Polls of 2 to 4 options for 5 minutes to 7 days. Choose who can reply, and add the Paid partnership or Made with AI label. (`x.poll`, `x.reply_settings`, `x.made_with_ai`) ### Post ```json { "content": "Post from your own code: SDKs in 8 languages.", "accounts": ["x"], "media_urls": [ { "url": "https://cdn.example.com/sdk.png", "alt": "SDK code" } ], "x": { "reply_settings": "following" }, "schedule_at": "2026-10-22T18:00:00Z" } ``` ### Long post ```json { "content": "New: Alt text on every image\n\nAdd accessibility descriptions to your media with the ALT button on each image in the composer. They publish natively to Mastodon, Bluesky, X and Pinterest.\n\nIt works in the API and MCP too: any media entry can now be { url, alt }, including per-tweet and per-toot media in threads.", "accounts": ["x"], "schedule_at": "2026-10-23T13:00:00Z" } ``` ### Thread ```json { "content": "", "accounts": ["x"], "x": { "thread_parts": [ { "text": "New: Best times to post", "media_ids": ["4211", "4212"] }, { "text": "When you schedule, you now see up to three recommended time slots for the channels you're posting to. One tap sets your time." }, { "text": "Open Analytics for a full week heatmap per platform. Every channel starts on cross-industry benchmarks, then switches to times calculated from when your own followers actually engage." } ] }, "schedule_at": "2026-10-27T09:00:00Z" } ``` ### Poll ```json { "content": "Which SDK do you use?", "accounts": ["x"], "x": { "poll": { "options": ["Node.js", "Python", "Go", "PHP"], "duration_minutes": 1440 } }, "schedule_at": "2026-10-25T10:00:00Z" } ``` ## Threads, chained for you Send 2 to 25 parts in one request. OmniSocials uploads each part’s media, posts the first tweet and adds every next part as a reply to the one before. Each tweet’s id and link come back on the post. `POST /v1/posts/create-and-publish`: ```json { "content": "", "accounts": ["x"], "x": { "thread_parts": [ { "text": "New: Alt text on every image", "media_urls": [ { "url": "https://cdn.example.com/alt-text.png", "alt": "The ALT button in the composer" } ] }, { "text": "Add accessibility descriptions to your media with the ALT button on each image in the composer. They publish natively to Mastodon, Bluesky, X and Pinterest." }, { "text": "It works in the API and MCP too: any media entry can now be { url, alt }, including per-tweet and per-toot media in threads." } ] } } ``` - **Chained in order.** Each part replies to the one before it, so X shows one thread. A poll, reply settings and labels go on the first tweet. (`x.thread_parts`) - **Media on every tweet.** Up to 4 images or one video per part, by URL or library id, each image with its own alt text. (`media_urls`, `media_ids`, `alt`) - **Every tweet’s link.** Once it is live, the post lists each tweet’s id and URL. If X stops halfway, the tweets that went out stay up and are listed. (`x.thread_tweets`, `published_urls.x`) ## Connect X once, post from code Sign in with X once inside OmniSocials. Create an API key, and your code posts, replies and reports for that account. - **Sign in with X.** X’s own sign-in, once, in the app. OmniSocials renews X’s two-hour tokens before they run out. - **A key per workspace.** A key only reaches its own workspace. Inbox access is switched on per key. - **Premium, detected.** The accounts call returns the X subscription: any paid tier raises posts to 25,000 characters, and Premium also allows longer videos. (`GET /v1/accounts`, `subscription_type`) `GET /v1/accounts?platform=x` answers: ```json { "data": [ { "id": "4127_x", "platform": "x", "display_name": "Omnisocials", "content_types": ["post"], "status": "active", "platform_details": { "subscription_type": "Premium" } } ], "workspace_name": "OmniSocials" } ``` ## Answer X DMs from your code Switch on X DMs in the Social Inbox, then list conversations and reply from your own code. X bills every DM, so they run on credits at X’s own rates. - **X DMs.** List conversations and reply from your own code. Comments and mentions on X stay out of the inbox. (`type=dm`, `/conversations/:id/reply`) - **Opt-in.** Someone with billing access switches X DMs on in the Social Inbox, with at least 25 credits on the balance. - **At X’s rates.** 1 credit per received DM and 2 per reply. At zero credits the X inbox pauses; top up and switch it back on. (`402 x_inbox_suspended`) `GET /v1/inbox/conversations?platform=x&type=dm` lists the conversations. Reply with `POST /v1/inbox/conversations/8812/reply`: ```json { "text": "Yes. Send the tweets in x.thread_parts, up to 25." } ``` ## Read what X reports Views, likes, replies, reposts, quotes and bookmarks per post, with link clicks and profile visits for the first 30 days. The API returns the same numbers the app charts. - **Per post.** Views, likes, replies, reposts, quotes and bookmarks. A thread comes back as one entry, its parts added up. (`/analytics/posts/:id`, `thread_parts`) - **The first 30 days.** Link clicks, profile visits and X’s own engagement count while a post is under 30 days old. Polls add their votes. (`link_clicks`, `profile_visits`) - **Per account.** Followers, following, posts and lists, saved once a day, so you can read any past day by date. X reports no reach. (`/analytics/accounts`, `date`) `GET /v1/analytics/posts/1019` answers: ```json { "data": { "post_id": "1019", "platforms": { "x": { "metrics": { "views": 92, "likes": 3, "comments": 1, "reposts": 1, "quotes": 0, "bookmarks": 2, "link_clicks": 2, "profile_visits": 3, "engagement": 12 }, "thread_parts": 1 } } } } ``` ## X’s rules, in one place OmniSocials checks every post against them before it reaches X, so a post that is too long fails in your request, not at publish time. | Limit | Value | | --- | --- | | Text | 280 characters, 25,000 on Basic or Premium | | Counting | A link counts 23, an emoji 2, like on X | | Media | Up to 4 images or one video, not both | | Images | JPEG, PNG or WebP up to 5 MB, alt text | | Video | 140 seconds, 125 minutes with Premium | | Thread | 2 to 25 tweets, up to 4 media each | | Poll | 2 to 4 options, 5 minutes to 7 days | | Link posts | 20 credits per tweet, X’s fee at cost | | X DMs | 1 credit per DM, 2 per reply | | Rate limit | 100 requests a minute per API key | ## Your first post in three steps About five minutes from sign-up to a scheduled post on X. Then hand the key to your coding agent. 1. **Create an API key** (`Settings › API`). Start your trial, open Settings, API and create a key. It is shown once. 2. **Connect your X account** (`GET /v1/accounts`). Sign in with X in OmniSocials once. Then list the account from your code. 3. **Send your first post** (`POST /v1/posts/create`). Post now with create-and-publish, or add schedule_at to plan it. ## FAQ ### Do I need my own X developer account? No. Your X account connects through OmniSocials’ X app, with X’s own sign-in. You call the OmniSocials API with an API key and never handle X tokens or an X billing account. ### Which X accounts can I post to? Any X account. Each workspace connects one; a second account goes in a second workspace with its own key. The same account can sit in several workspaces. ### Does the API know about X Premium? Yes. OmniSocials reads the account’s subscription when it connects, and GET /v1/accounts returns it. Basic, Premium and Premium+ accounts post up to 25,000 characters; Premium and Premium+ also get videos up to 125 minutes. Free accounts get 280 characters, and free and Basic accounts 140-second videos. After an upgrade, reconnect X once so the new limits apply. ### How are characters counted? The way X counts them. Every link counts as 23 characters whatever its length, and emoji and some symbols count as 2. A post over the limit fails in your request with an error that says so, not at publish time. ### Can I publish threads? Yes. Send 2 to 25 parts in x.thread_parts, each with its own text and up to 4 images or one video. OmniSocials posts them in order, each as a reply to the one before, and lists every tweet’s id and link in x.thread_tweets once it is live. ### Can I add polls, reply settings and labels? Yes. x.poll takes 2 to 4 options of up to 25 characters and duration_minutes from 5 to 10,080 (7 days); a poll can’t go with media. x.reply_settings limits replies to people you follow or people you mention, and paid_partnership and made_with_ai add X’s labels. ### What does X charge for posts with a link? X bills posts with a link at a higher rate, and OmniSocials passes that fee through at cost: 20 credits per tweet with an http:// or https:// link, counted per part in a thread. A bare domain such as omnisocials.com costs nothing, and neither do posts without a link or analytics. Credits cost €0.01 each. Connecting X adds 200 credits once, and the 201 answer warns you when a post will use credits. ### Can I read and answer X DMs? Yes, once someone with billing access switches X DMs on in the Social Inbox. X bills every DM, so they run on credits: 1 per received DM and 2 per reply. Comments and mentions on X are not part of the inbox. ### What does X report on my posts? Views, likes, replies, reposts, quotes and bookmarks, and for posts under 30 days old also link clicks, profile visits and X’s engagement count. Polls return their votes per option. X reports no reach. A thread comes back as one entry with its parts added up. ### How do webhooks work? Register a URL and pick the events: post.scheduled, post.published, post.failed, post.approved and post.rejected. Every delivery is signed with HMAC-SHA256 in the X-OmniSocials-Signature header. ### Is the X API free? No. X bills its own API per use. With OmniSocials you need no X developer account and get no X bill: the API is part of the plan, $10 per seat per month billed annually. Only X’s own fees pass through, at cost: 20 credits per tweet with a link, 1 credit per received DM and 2 per reply, at €0.01 a credit. Posts without a link and analytics add nothing. ### What are the rate limits? 100 requests a minute per API key. Past that the API answers 429 with a Retry-After header that says when to try again. Inbox replies are capped at 1,000 a day per workspace. ### How much does OmniSocials cost? One plan with every feature included: $10 per seat per month billed annually, or $12 billed monthly. Team members and client seats cost the same. Every account starts with a 14-day free trial. The REST API, the SDKs, the CLI, webhooks and the MCP server are part of that one plan. ## Pricing From $10 per seat a month, API included. 14-day free trial. ## Related - [X (Twitter) scheduler](https://omnisocials.com/x.md) - [X (Twitter) MCP server](https://omnisocials.com/x-mcp.md) - [All channels](https://omnisocials.com/channels.md) - [X (Twitter) character limits](https://omnisocials.com/twitter-character-limits) - [X (Twitter) video lengths](https://omnisocials.com/twitter-video-lengths) ## Links - Page: https://omnisocials.com/x-api - X platform docs: https://docs.omnisocials.com/platforms/x - API reference: https://docs.omnisocials.com/api - REST API overview: https://omnisocials.com/api.md - MCP server: https://omnisocials.com/mcp.md - Sign up: https://app.omnisocials.com/signup