X API: Post a Tweet
How to publish a post to X (formerly Twitter) via API.
By André LugConnect an X profile — your own OAuth 1.0a developer app or PostGate’s house app — then send one POST /api/posts call with the profile ID, a body, and any media. PostGate validates X’s 280-character weighted limit and media rules before sending, and X’s per-action charge applies via your own app or your workspace credit balance.
This is the shortest path from a piece of content to a live post on X (formerly Twitter): one connected profile, one POST /api/posts call. For the full walkthrough with error handling and delivery polling, see How to Post to X via API. If you want the raw X API v2 call underneath, see Twitter API v2: Create a Tweet.
X is the one platform in PostGate where publishing has a direct dollar cost per action — worth understanding before your first request. You can start in the sandbox for free to see the full request/response shape before connecting a real X account.
Connect an X profile
curl -X POST https://postgate.studio/api/profiles/connect \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "x",
"profile_group_id": "grp_acme123",
"return_url": "https://app.example.com/settings/social"
}'Publish the post
Idempotency-Key makes the request safe to retry.curl -X POST "https://postgate.studio/api/posts?profile_group_id=grp_acme123" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-post-x-001" \
-d '{
"post": { "body": "Launch day. 🚀" },
"profiles": ["pro_x123"],
"media": ["https://cdn.example.com/launch.jpg"]
}'What does this request actually cost?
Text and media limits enforced before you pay for it
Read back the result
curl https://postgate.studio/api/posts/post_01JXYZ \
-H "Authorization: Bearer $POSTGATE_API_KEY"Frequently asked questions
Does posting to X through the API cost money?
Yes — X charges per post and per analytics read, a real mechanic rather than a PostGate markup. Bring your own X developer app and you publish at no credit cost to your PostGate workspace; use PostGate’s shared app instead and the equivalent charge is drawn from your workspace credit balance.
What are the text and media limits for an X post?
PostGate validates against X’s real limits before sending: 280 characters using X’s weighted counting (URLs and non-Latin characters don’t count 1:1 with plain ASCII), up to 4 media items, images up to 5 MB, and MP4 video up to 512 MB and 140 seconds. Larger video goes through chunked media upload first.
What kind of OAuth does X publishing require?
An X developer app with OAuth 1.0a enabled — the classic “API Key” / “API Key Secret” consumer credentials, not the OAuth 2.0 client ID/secret pair most other platforms use. Alternatively, use PostGate’s house app and draw down your workspace credit balance instead.
How do I confirm the post was delivered?
The response includes a per-target status, the platform post ID, and the permalink once delivered. Poll the post with GET /api/posts/{id} if you need to wait for a not-yet-terminal target.
