How to Schedule X (Twitter) Posts via API
Publish tweets to X using the PostFast API. Schedule text, images, videos, and multi-image posts programmatically.
X (formerly Twitter) posts are short, real-time updates that appear on your profile and in followers' timelines. Using the PostFast API, you can schedule tweets with text, images, or video to any connected X account.
A standard tweet on X carries a 280-character text limit plus either up to 4 images or 1 video as media. You cannot mix images and videos in the same post. Text-only posts are fully supported - simply omit the mediaItems array.
To retweet an existing tweet without modification, use the xRetweetUrl control (covered in the retweets guide).
Code Example
const response = await fetch('https://api.postfa.st/social-posts', {
method: 'POST',
headers: {
'pf-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"posts": [
{
"content": "Just shipped: automated cross-posting to 11 platforms from one API call.\n\nFull dev docs: https://postfa.st/docs",
"mediaItems": [
{
"key": "image/b1c2d3e4-f5a6-7890-1234-567890abcdef.jpg",
"type": "IMAGE",
"sortOrder": 0
}
],
"scheduledAt": "2026-05-01T14:00:00.000Z",
"socialMediaId": "aa1a3044-98aa-07b2-b493-221232117009"
}
],
"controls": {}
})
});
const data = await response.json();
Did You Know?
Tips
Stay within your plan's per-account daily limit (6-9 posts depending on plan) - exceeding it causes posts to fail at publish time
All workspaces in your organization share the same daily X/Twitter pool - budget accordingly if you run multiple brands
Use sortOrder to control image ordering in multi-image posts - lowest sortOrder appears first
To retweet an existing post, use the xRetweetUrl control instead of crafting a new post (see retweets guide)
Use the top-level firstComment field to auto-post a reply ~10 seconds after your tweet publishes
Schedule to X and 10 other platforms from one API
Common Pitfalls
You cannot combine images and video in the same X post. Pick one media type per post - any mixed payload will be rejected.
PostFast enforces plan-specific per-account daily caps on X (6-9 depending on plan). Scheduling more will cause later posts to fail at publish time. See /fair-usage for exact numbers.
X limits a single post to 4 images maximum. Any 5th+ image in mediaItems will cause the post to fail.
All workspaces in your organization share one daily X/Twitter pool. An agency with 12 X accounts on Growth has 42 total posts/day across the org - not 12 × 7 = 84.
Frequently Asked Questions
What is the character limit for X posts via API?
X's standard tweet limit is 280 characters. We recommend staying within 280 for reliable delivery across all account types.
Can I schedule text-only tweets?
Yes. Omit the mediaItems array (or pass an empty array) and the post will publish as text-only.
Can I mix images and video in one tweet?
No. X requires that each post contain either images (up to 4) or one video - not both. Attempts to combine them will be rejected.