X

Publish posts, threads, replies, quotes, polls and long-form Articles to X, edit recent posts, and act as the account (retweet, bookmark, follow, search). The same connection reads post analytics, sends and receives DMs and manages replies to your posts. In the API the platform id is twitter; everywhere a person reads it, show X.

#What you can do

#Connect

With a card on file, call the connect endpoint with a profileId and send the user to authUrl. After they approve, they land on your redirect_url with connected=twitter, profileId and accountId appended.

curl "https://api.pozy.ai/v1/connect/twitter?profileId=6720c0f24f3b2e0018d4a6e0&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/twitter?profileId=6720c0f24f3b2e0018d4a6e0&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

// Redirect the user to data.authUrl

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/connect/twitter",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "6720c0f24f3b2e0018d4a6e0", "redirect_url": "https://app.example.com/connected"},
)
print(resp.json()["authUrl"])

If the user denies consent, they come back with error=oauth_denied&platform=twitter on the redirect URL. Treat any other error value as a generic failure.

#Spend cap

Each workspace can set a monthly cap on X spend in billing settings. Pozy emails a warning at 80% of the cap. At the cap, every billable X call (posts, DMs, reads) is refused before it reaches X with 402 and code x_spend_cap_reached, until the cap is raised or the month rolls over. Drafts never count.

#Post types

curl -X POST https://api.pozy.ai/v1/posts \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Release 2.4 is out: faster sync and a new export screen.",
    "mediaItems": [{ "type": "image", "url": "https://cdn.example.com/release-2-4.png" }],
    "platforms": [{ "platform": "twitter", "accountId": "6720c1a94f3b2e0018d4a7f6" }],
    "publishNow": true
  }'

const res = await fetch("https://api.pozy.ai/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Release 2.4 is out: faster sync and a new export screen.",
    mediaItems: [{ type: "image", url: "https://cdn.example.com/release-2-4.png" }],
    platforms: [{ platform: "twitter", accountId: "6720c1a94f3b2e0018d4a7f6" }],
    publishNow: true,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

console.log(data.post.platforms[0].platformPostUrl);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "content": "Release 2.4 is out: faster sync and a new export screen.",
        "mediaItems": [{"type": "image", "url": "https://cdn.example.com/release-2-4.png"}],
        "platforms": [{"platform": "twitter", "accountId": "6720c1a94f3b2e0018d4a7f6"}],
        "publishNow": True,
    },
)
print(resp.json()["post"]["platforms"][0]["platformPostUrl"])

#Thread

Put the whole sequence in platformSpecificData.threadItems. Item 0 is the first post and each item replies to the one before. Each item can have its own mediaItems. When threadItems is set, the top-level content is kept for search and display in Pozy but is not published, so the first post must be threadItems[0].

{
  "platform": "twitter",
  "accountId": "6720c1a94f3b2e0018d4a7f6",
  "platformSpecificData": {
    "threadItems": [
      { "content": "How we halved our cloud bill in 6 weeks. A thread.", "mediaItems": [{ "type": "image", "url": "https://cdn.example.com/bill-chart.png" }] },
      { "content": "1. We turned off every environment nobody had logged into for 30 days." },
      { "content": "2. We moved batch jobs to spot instances." },
      { "content": "3. We set budgets per team, with alerts. That one changed behaviour fastest." }
    ]
  }
}

A thread cannot carry a poll.

#Reply and quote

• Reply: replyToTweetId with the id of the post. X only accepts replies to your own posts or posts that mention you. Combine it with threadItems to reply with a whole thread; only the first item replies to the target. It cannot be combined with replySettings.
• Quote: quoteTweetId with the post id or its full URL. X only accepts quotes of your own posts, posts that mention you, or posts in a conversation you are part of. A quote cannot carry media or a poll. A quote made this way is billed at the normal post rate, while pasting the post's URL into content is billed as a post with a link, which costs much more.

To find ids, use Search recent tweets (the last 7 days) or resolve a URL with Look up a tweet.

#Poll

poll takes 2 to 4 options of 1 to 25 characters and duration_minutes from 5 to 10,080 (7 days). It cannot be combined with media, threadItems or quoteTweetId.

"platformSpecificData": {
  "poll": { "options": ["Dark mode", "Offline sync", "More exports"], "duration_minutes": 1440 }
}

#Article

article publishes a long-form X Article on an eligible Premium+ account. It needs a title and a content_state in X's own block format (blocks with types such as unstyled, header-one, ordered-list-item, plus entities for links and images). mode: "draft" stops after creating the draft on X; publish (default) publishes it and makes two billable X calls. An optional cover.url takes a public JPG, PNG or WebP. Articles cannot be combined with any other post option.

#Platform fields

Schema: TwitterPlatformData.

#Edit a published post

Edit published post with platform: "twitter" changes the text, but X only allows it on accounts with X Premium, within 1 hour of publishing, up to 5 times, on single posts (not threads), and for text only. X creates a new post id on every edit and Pozy returns it as id. Outside those rules the call returns 400.

Unpublish deletes a published post from X.

#Media requirements

A post carries up to 4 images, or 1 GIF, or 1 video. Use direct file URLs or upload the file.

Send a GIF as type: "gif".

#Limits

If X rate-limits an account, Pozy pauses publishing on it for 10 minutes, doubling on each further hit within 24 hours. Posts scheduled inside the pause fail with the same message. X rejects text it already has from the account, so repeated posts need changes.

The API cannot use Spaces, post to Communities, pin a post to the profile, create cards (use meta tags on the linked page) or send broadcast DMs.

#Analytics

GET /v1/analytics?platform=twitter returns impressions, likes, comments, shares, saves (bookmarks), clicks and views per post. views is X's media view count, so text and image posts report 0. The date range defaults to the last 90 days and can be up to 366 days. Every analytics read is an X call billed at X's rate.

#Engagement

Act as a connected account with the X Engagement endpoints. Each POST has a DELETE on the same path to undo it.

A 403 means X refused the action for this account, usually a missing permission or a suspended account. Reconnect and accept every permission.

#Inbox

DMs. Start a conversation with Create conversation, passing accountId, the recipient as participantUsername or participantId, and message. An existing conversation with that person is reused. Pozy first checks that the person accepts DMs from you and returns 422 DM_NOT_ALLOWED if not; pass skipDmCheck: true when you have already checked.

curl -X POST https://api.pozy.ai/v1/inbox/conversations \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "6720c1a94f3b2e0018d4a7f6", "participantUsername": "acme_support", "message": "Thanks for flagging this. Which screen showed the error?" }'

Later messages go through Send message and can include images or video up to 25 MB. Conversation lists are cached for 2 minutes. X's newer encrypted chat is not visible to any third-party app, so some conversations may look empty or show only your side. X DMs are billed at X's rate, not on Pozy's outbound message meter.

Comments are the replies to your posts. Reply with Reply to comment, adding commentId to answer a specific reply. postId can be the Pozy post id or the X post id, so posts made outside Pozy work too. You can also like, hide and delete replies. Send an Idempotency-Key when you retry, so a retry never posts twice.

#Errors you may see

A rejected publishNow: true post returns 207 with post.status: "failed" and the reason in platforms[].errorMessage. A failed X post is not retried automatically.

#Endpoints

#Webhook events