Twitter / X - letmepost.dev

Before you start. Every URL costs 23 characters regardless of its real length — even after t.co wrapping. The grapheme counter subtracts the raw URL and adds the t.co weight so the 280-character preflight matches X’s server-side count exactly. Long links don’t help you fit; they just hurt the visible text.

Quick reference

Limit / capability	Value
Character limit	280 graphemes (t.co-weighted)
Images per tweet	4
Image formats	jpeg, png, webp
Image size	5,000,000 bytes (5 MB)
GIF size	15,000,000 bytes (15 MB)
Video formats	mp4 (H.264 + AAC recommended)
Video size	512,000,000 bytes (512 MB)
Video duration	140 s on the standard tier (platform-enforced)
Mixed image + video	Rejected — pick one per tweet
Alt text per item	1,000 graphemes (best-effort write)
Post types supported	text, single image, multi-image, single video, single GIF, reply, quote
Scheduling	Yes (via `scheduledAt`)
Thread (reply chain)	Yes (`twitter.replyToTweetId`)
Quote tweet	Yes (`twitter.quoteTweetId`)
First comment	Not supported (use a reply chain)
Inbox / DM	Not supported in v1
Analytics	Not supported in v1

Connect an account

POST /v1/accounts/connect/twitter. OAuth 2.0 PKCE. letmepost signs a state token carrying the PKCE code_verifier through the redirect so the dashboard never stashes it client-side. After the X callback, the code+verifier exchange runs server-side.

Scopes

tweet.write     — create tweets
tweet.read      — required to mint the token
users.read      — required to mint the token
offline.access  — required for refresh tokens

Extended: like.read, follows.read — off by default; not needed for publishing.

Token lifecycle

X access tokens are short-lived (~2 hours); offline.access mints a refresh token that lets the publisher refresh on schedule. If a user revokes app access from X’s settings the next call surfaces platform_auth_failed.

Post types

Text post

text.json

{
  "targets": [{ "accountId": "..." }],
  "text": "shipped"
}

Single image

single-image.json

{
  "targets": [{ "accountId": "..." }],
  "text": "shipped",
  "media": [{ "kind": "image", "mediaId": "med_…", "altText": "..." }]
}

Multi-image (up to 4)

multi-image.json

{
  "targets": [{ "accountId": "..." }],
  "text": "four shots",
  "media": [
    { "kind": "image", "mediaId": "med_a…", "altText": "front" },
    { "kind": "image", "mediaId": "med_b…", "altText": "back" },
    { "kind": "image", "mediaId": "med_c…", "altText": "left" },
    { "kind": "image", "mediaId": "med_d…", "altText": "right" }
  ]
}

Single video

Chunked upload runs transparently — small clips return immediately, larger ones run INIT → APPEND → FINALIZE → STATUS until X reports succeeded.

video.json

{
  "targets": [{ "accountId": "..." }],
  "text": "demo clip",
  "media": [{ "kind": "video", "mediaId": "med_…" }]
}

Reply (and threads)

Threads on X are reply chains — pass the previous tweet id on each follow-up. The first tweet in a thread is just a normal post; the second carries replyToTweetId set to the first’s id, the third to the second’s, and so on.

reply.json

{
  "targets": [
    {
      "accountId": "...",
      "options": { "platform": "twitter", "replyToTweetId": "1700000000000000001" }
    }
  ],
  "text": "(2/3) more details"
}

Quote tweet

Mutually exclusive with replyToTweetId — preflight rejects setting both, since X itself does.

quote.json

{
  "targets": [
    {
      "accountId": "...",
      "options": { "platform": "twitter", "quoteTweetId": "1700000000000000001" }
    }
  ],
  "text": "this is huge"
}

Wisdom (platform-specific things that bite)

Every URL costs 23 characters regardless of length. The counter subtracts the real URL and adds the t.co weight, so a 3-char shortlink and a 300-char tracking URL both weigh 23.
Alt text is best-effort. The /1.1/media/metadata/create write happens on a deprecation track separate from /2/tweets; if the metadata write fails, the tweet still posts. You don’t lose the post — you lose the accessibility text.
The free posting tier was retired in 2025; new developers go through Pay Per Use or a paid tier. letmepost works on any tier with tweet.write. The launch-cap preflight (twitter.launch_cap.per_account) surfaces per-account ceilings before X 429s.
replyToTweetId and quoteTweetId are mutually exclusive — X rejects tweets with both. Preflight catches this locally before the upstream round-trip.
Chunked video uploads use 4 MiB segments. The publisher polls the FINALIZE → STATUS loop and surfaces failures as twitter.media.video_processing_failed with the upstream processing_info.error attached.
GIFs are not “images” on X — they have their own 15 MB ceiling (twitter.media.gif_size_max) distinct from static images’ 5 MB.
Mixed image + video isn’t allowed on the same tweet; carousel of mixed media doesn’t exist on X. Pick one kind per tweet, or chain a thread.

Common errors

Error rule	What it means	How to fix
`twitter.text.max_graphemes`	Weighted character count > 280	Trim text or shorten URLs (won’t help past 23 chars/URL).
`twitter.text.non_empty`	Tweet body was empty	Provide non-whitespace text — X requires it even on media tweets.
`twitter.media.count_max`	> 4 images, or > 1 video/GIF	Up to 4 images, 1 video, or 1 GIF per tweet.
`twitter.media.image_video_exclusive`	Mixed image + video	Pick one media kind per tweet.
`twitter.media.image_size_max`	Image > 5 MB	Re-encode under 5,000,000 bytes.
`twitter.media.gif_size_max`	GIF > 15 MB	Re-encode under 15,000,000 bytes.
`twitter.media.video_size_max`	Video > 512 MB	Compress under 512,000,000 bytes.
`twitter.media.video_processing_failed`	FINALIZE / STATUS returned an error	Inspect `platformResponse.processing_info.error` for the codec / container reason.
`twitter.media.processing_timeout`	STATUS poll exceeded the deadline	Retry; X’s transcoder sometimes lags.
`twitter.launch_cap.per_account`	Per-account launch-cap exhausted	Wait for the cap window to roll over, or upgrade the X tier.

What you can’t do (yet)

Polls.
Long-form (premium) tweets above 280 graphemes — the preflight cap is wired for the standard limit; long-form support lands in a follow-up slice.
Reading replies, likes, or retweet metadata.
DMs.
Lists (creating tweets that target a list audience).
Spaces.

API reference

POST /v1/posts — primary publish.
POST /v1/media — upload images/videos for mediaId references.
POST /v1/accounts/connect/twitter — start a Twitter OAuth flow.

​Quick reference

​Connect an account

​Scopes

​Token lifecycle

​Post types

​Text post

​Single image

​Multi-image (up to 4)

​Single video

​Reply (and threads)

​Quote tweet

​Wisdom (platform-specific things that bite)

​Common errors

​What you can’t do (yet)

​API reference

Quick reference

Connect an account

Scopes

Token lifecycle

Post types

Text post

Single image

Multi-image (up to 4)

Single video

Reply (and threads)

Quote tweet

Wisdom (platform-specific things that bite)

Common errors

What you can’t do (yet)

API reference