X (Twitter) posting API
Publish and schedule X posts from your own code with one REST request. This page covers what X accepts, the limits FoPost applies, and a request you can run.
What you can post to X
Pick the shape with artifact_type on the post. The same request body works for every network, so a post can target X and other accounts at once.
Post
Text, with media where the network takes it.
"artifact_type": "text_post"Thread
Each content block becomes one post in the chain.
"artifact_type": "thread"Article
A title and a long-form body.
"artifact_type": "article"Carousel
Several images in a fixed order, in one post.
"artifact_type": "carousel"Link
A URL in the text, shown as a preview card.
"artifact_type": "link_share"
X limits through the API
The ceilings FoPost delivers to X. A post that breaks one is reported by POST /v1/posts/{id}/preflight before anything is sent.
- Text
- 280, or 25,000 with X PremiumEvery URL counts as 23 characters.
- Media per post
- Up to 4
- Formats
- JPEG, PNG, GIF, WebP, MP4
- Image size
- Up to 5 MB
- Video size
- Up to 512 MB
- Video length
- Up to 2:20 minutes
- Alt text
- 1,000 characters per image
Media is a list of type, name and url on a content block. Files up to 100 MB can be sent with the request as multipart form data; larger ones go through direct upload first and are attached by URL.
Schedule a post to X
Create the post with POST /v1/posts and an API key in the X-API-Key header. accounts takes the id of your connected X account, which GET /v1/accounts lists.
contentis a list of blocks. With artifact_type thread, each block is one post in the X thread.titlesets the title, on the X post types that take one.statusscheduledwithschedule_atpublishes at that time. Leave both out to save a draft.settingsholds per-account options, keyed by account id. This example setsreply_settings.- The response is the created post, with its id and status.
curl -X POST https://api.fopost.com/v1/posts \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90",
"accounts": [
"3a9f1d20-6c77-4b2e-9a01-8f5d2c3b4e10"
],
"artifact_type": "thread",
"content": [
{
"text": "We just shipped scheduled exports."
},
{
"text": "Here is how they work, step by step."
}
],
"status": "scheduled",
"schedule_at": "2026-12-01T15:00:00Z",
"settings": {
"3a9f1d20-6c77-4b2e-9a01-8f5d2c3b4e10": {
"reply_settings": "following"
}
}
}'Publish now, later, or after review
Creating and editing posts needs the posts scope. Publishing, retrying and cancelling need publish as well, so a key can manage drafts without being able to send anything to X.
- Schedule
schedule_atsets the time, or"schedule": "queue"takes the next free posting slot.- Publish now
POST /v1/posts/{id}/publishanswers 202 and queues delivery. Withoptions.dryRunit validates without sending.- Approval
- When the workspace requires approval, the post is held as
pending_approvaland publish answers withheld: true. Nothing reaches X until a reviewer approves it. - Result
GET /v1/posts/{id}/deliveriesreturns the status, permalink and any X error, or subscribe to thedelivery.publishedanddelivery.failedwebhooks.
curl -X POST https://api.fopost.com/v1/posts/$POST_ID/publish \
-H "X-API-Key: $API_KEY"curl https://api.fopost.com/v1/posts/$POST_ID/deliveries \
-H "X-API-Key: $API_KEY"Requests per minute, per key
The ceiling grows with the number of connected accounts on your billing account. API requests are free within it.
- Up to 2 accounts
- 60 requests per minute
- 3 to 2,000 accounts
- 600 requests per minute
- 2,001 or more accounts
- 1,200 requests per minute
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit, the API answers 429 too_many_requests with a Retry-After header.
X applies its own posting limits per account. When it throttles one, the delivery waits as long as X asks and reports delayed until it goes out.
Edit and remove live X posts
- Edit a live post
- No. X’s API cannot edit a published post, so change it before it goes out.
- Unpublish
- Yes.
POST /v1/posts/{id}/unpublishtakes it down on X.