X (Twitter) API

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.

Post types

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"
Limits

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.

Request

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.

  • content is a list of blocks. With artifact_type thread, each block is one post in the X thread.
  • title sets the title, on the X post types that take one.
  • status scheduled with schedule_at publishes at that time. Leave both out to save a draft.
  • settings holds per-account options, keyed by account id. This example sets reply_settings.
  • The response is the created post, with its id and status.
POST /v1/posts
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"
      }
    }
  }'
Scheduling and approvals

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_at sets the time, or "schedule": "queue" takes the next free posting slot.
Publish now
POST /v1/posts/{id}/publish answers 202 and queues delivery. With options.dryRun it validates without sending.
Approval
When the workspace requires approval, the post is held as pending_approval and publish answers with held: true. Nothing reaches X until a reviewer approves it.
Result
GET /v1/posts/{id}/deliveries returns the status, permalink and any X error, or subscribe to the delivery.published and delivery.failed webhooks.
Publish now
curl -X POST https://api.fopost.com/v1/posts/$POST_ID/publish \
  -H "X-API-Key: $API_KEY"
Read the result
curl https://api.fopost.com/v1/posts/$POST_ID/deliveries \
  -H "X-API-Key: $API_KEY"
Rate limits

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.

After publishing

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}/unpublish takes it down on X.