Twitter / X

Overview

Publish tweets, threads, polls, and rich media to Twitter/X through a single API endpoint. PostPeer handles OAuth, token refreshes, and rate limits.

X is the most expensive API PostPeer talks to, and it's the only platform with non-uniform credit pricing. X bills us per request, and posts containing a link are priced at roughly 13× the rate of plain text. We pass that through:

Post on X (no URL): 5 credits
Post on X with a URL: 50 credits
Every other platform: 1 credit per post

If you're cross-posting to several platforms, expect the X line to dominate your usage. See Pricing below for the full breakdown.

Quick Start

1. Connect a Twitter Account

curl https://api.postpeer.dev/v1/connect/twitter \
  -H "x-access-key: YOUR_API_KEY"

Response:

{
  "url": "https://twitter.com/i/oauth2/authorize?..."
}

Redirect the user to the url. After authorization, the account is connected to your project. See Connect Accounts for the full OAuth flow.

2. Get the Account ID

curl https://api.postpeer.dev/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"

Find the integration with "platform": "twitter" and note the id.

3. Post a Tweet

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from PostPeer!",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "publishNow": true
  }'

Response:

{
  "success": true,
  "status": "published",
  "postId": "post_xyz789",
  "platforms": [
    {
      "platform": "twitter",
      "success": true,
      "platformPostUrl": "https://twitter.com/you/status/123456"
    }
  ]
}

Features

Text Posts

Post a standard tweet with up to 280 characters.

Images & Videos

Attach media using the mediaItems array:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Check out this photo!",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/photo.jpg" }
    ],
    "publishNow": true
  }'

Supported media:

Images: JPG, PNG, GIF, WebP (up to 4 per tweet)
Videos: MP4 (1 per tweet)
GIFs: animated GIF (1 per tweet)

Threads

Create multi-tweet threads using platformSpecificData.threadItems:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "1/ Here'\''s a thread about our API...",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "threadItems": [
            { "text": "2/ Connect any social account via OAuth" },
            { "text": "3/ Post to all platforms with one request" }
          ]
        }
      }
    ],
    "publishNow": true
  }'

Polls

Create polls with 2-4 options:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What should we build next?",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "poll": {
            "options": ["Analytics", "Webhooks", "Bulk upload"],
            "durationMinutes": 1440
          }
        }
      }
    ],
    "publishNow": true
  }'

Community Posts

Publish a tweet into a Twitter Community by providing platformSpecificData.communityId. Optionally set shareWithFollowers to true to also share the post with your followers.

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Excited to share this with the community!",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "communityId": "1234567890",
          "shareWithFollowers": true
        }
      }
    ],
    "publishNow": true
  }'

Field	Type	Description
`communityId`	`string`	The ID of the Twitter Community to post into
`shareWithFollowers`	`boolean`	Also share the Community post with your followers (default `false`)

Reply to a Tweet

Post a tweet as a reply to an existing tweet by providing platformSpecificData.replyToTweetId:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Great point!",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "abc123",
        "platformSpecificData": {
          "replyToTweetId": "1234567890"
        }
      }
    ],
    "publishNow": true
  }'

Replying is not always available. It depends on the reply settings the original author picked for their tweet (e.g. everyone, people you follow, verified accounts, or mentioned users only). If your account doesn't match the author's selection, the reply will fail.

Reply Settings

Control who can reply to your tweet using platformSpecificData.replySettings:

"everyone" (default)
"following"
"mentionedUsers"

Limits

Limit	Value
Character limit	280 per tweet
Images per tweet	4
Videos per tweet	1
Thread length	No hard limit
Poll options	2-4

Pricing

Most platforms cost a flat 1 credit per post. X is the exception, because X charges PostPeer differently for plain tweets and tweets with links. Rather than spread that markup across every platform's base rate, we keep it isolated to X.

Action	Credits	Notes
Post on X (no URL)	5	Text, image, video, GIF, poll, thread without links
Post on X with a URL	50	Body contains `http://` or `https://`
Post on any other platform	1	Instagram, LinkedIn, TikTok, YouTube, Pinterest, Facebook, Threads, Bluesky
Analytics request	1	One credit per call, regardless of how many posts come back

The split mirrors X's own developer pricing:

X API operation	X's rate	Why it matters
Content: Create	`$0.015` per request	Plain tweet, no link
Content: Create (with URL)	`$0.200` per request	Any `http(s)://` in the body, ~13× the plain rate
Posts: Read	`$0.005` per resource	Analytics lookups, post fetches

This is X's pricing, not PostPeer's markup. The full rate sheet lives at docs.x.com/x-api/getting-started/pricing. If you don't need the link to be a real hyperlink, dropping it from the body takes the same tweet from 50 credits down to 5.

On this page