Skip to content
postpeg
Start trial

X API

Post to X from your app, without building an X integration

postpeg gives your product one REST endpoint for X and nine other networks. You send the text and media once, and postpeg checks the post against X’s rules, publishes it through X’s official API, and tells you how it went, account by account.

Start 7-day trialRead the docs
  • Publish
  • Schedule
  • Analytics
  • X112/280
    image

    Scheduled posts now retry on their own when a network has a bad minute. Changelog: https://example.com/changelog

    Ready

The example below, checked against X’s rules

Teams use it to post changelogs and release notes, to let their own users schedule tweets from inside a product, and to read impressions and engagement back without keeping an X client of their own up to date.

What you can do on X

  • Publish. Publish to X now with POST /v1/posts, alone or in the same request as any of the other networks. More on the Posting API.
  • Schedule. Schedule up to a year ahead with scheduled_at, and cancel with DELETE /v1/posts/{id} any time before it goes out. More on the Scheduling API.
  • Analytics. Read impressions, likes, shares and more per post with GET /v1/posts/{id}/analytics, and follower growth with GET /v1/accounts/{id}/analytics. More on the Analytics API.

Not available on X: comments and direct messages. The coverage table shows what each network supports.

X’s rules, checked before sending

A X post can have up to 280 characters, counted as people see them (an emoji is one). Media is optional: up to 4 images or 1 video. postpeg runs these checks on every request, so a post that won’t fit X is refused with a 400 before anything is published, on any network.

X limits as postpeg checks them
Max text280 characters
MediaOptional
Images4
Videos1
Images and video togetherNone
Required optionsNone
Connects withHosted OAuth

Connecting X accounts

Call POST /v1/accounts/connect with a profile and "platform": "x", and send the account’s owner to the URL you get back. It’s valid for 15 minutes. They approve access on X’s own screen and land on your redirect_url with status=success and the new account_id.

Each X account is connected by its owner through a hosted OAuth screen, so your app never handles an X password or stores X tokens itself.

If X ever expires a login, the account turns reconnect_required so you can ask its owner to connect again. More in Profiles and accounts.

Example: a scheduled X post

One request, with an Idempotency-Key so a retry on your side never posts twice. To post to X and other networks together, add more ids to account_ids.

curl https://api.postpeg.com/v1/posts \
  -H "Authorization: Bearer $POSTPEG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: x-example-2026-10-01" \
  -d '{
    "account_ids": [
      "acc_mfz1x0k27d4q8vbn3c5s0a1p9e"
    ],
    "content": "Scheduled posts now retry on their own when a network has a bad minute. Changelog: https://example.com/changelog",
    "media": [
      {
        "url": "https://example.com/changelog.png",
        "type": "image",
        "alt_text": "Changelog"
      }
    ],
    "scheduled_at": "2026-10-01T09:00:00Z",
    "platform_options": {}
  }'
Response · 201 Created
{
  "id": "post_mfz2k3v8q1w5e9r4t7y0u2i6o3",
  "content": "Scheduled posts now retry on their own when a network has a bad minute. Changelog: https://example.com/changelog",
  "media": [
    {
      "url": "https://example.com/changelog.png",
      "type": "image",
      "alt_text": "Changelog"
    }
  ],
  "platform_options": {},
  "status": "scheduled",
  "scheduled_at": "2026-10-01T09:00:00.000Z",
  "targets": [
    {
      "account_id": "acc_mfz1x0k27d4q8vbn3c5s0a1p9e",
      "platform": "x",
      "status": "pending",
      "platform_post_id": null,
      "url": null,
      "error": null,
      "attempts": 0,
      "published_at": null
    }
  ],
  "created_at": "2026-09-24T14:02:11.418Z"
}

From 09:00 the target moves through queued and publishing to published with the live url, or to failed with the reason in error. Temporary failures are retried, up to 5 attempts with growing waits. See Publishing for every status.

Questions

How do I schedule a X post?
Add scheduled_at (ISO 8601, up to a year ahead) to POST /v1/posts. The post waits as scheduled and goes out within a minute of that time. DELETE /v1/posts/{id} cancels it any time before.
What happens if a post breaks X’s rules?
postpeg checks the text (up to 280 characters), the media before anything is sent. A post that doesn’t fit comes back as a 400 with every problem listed in issues, and nothing is published on any network.
Which X features does postpeg support?
Publishing, scheduling, analytics. Comments and direct messages are not available on X; asking for them returns a 400 naming the feature.
Does postpeg count X characters the way X does?
postpeg counts characters as people see them (an emoji or an accented letter is one) and refuses anything over 280 before sending. X itself weighs some characters, such as emoji, as two, so a post right at the limit is safest kept a little shorter.
Can I attach a video and images to the same X post?
No. An X post takes up to 4 images or 1 video. A request that mixes them, or has more, comes back as a 400 with the problem in issues, and nothing is published.

Also on the line

The same request publishes to all ten networks. Often paired with X:

Or see all 10: Instagram, Facebook, LinkedIn, TikTok, YouTube, Threads, Pinterest, Bluesky and Google Business, in the platform reference.

Send your first post in a few minutes

The 7-day trial has every feature and 3 connected accounts, with no card. The quickstart takes you from a key to a published post.

Start 7-day trialRead the quickstartSee pricing