How to Schedule X Carousel Posts via API
Publish multi-image tweets (up to 4 photos) to X using the PostFast API. Perfect for product showcases, tutorials, and visual storytelling.
X supports multi-image tweets with up to 4 photos attached to a single post. These appear as a grid (2x2, 1x2, or 1x3 depending on count) on the timeline and expand to a full-screen carousel when tapped. Using the PostFast API, you create a carousel by attaching multiple IMAGE items to the same post's mediaItems array.
There is no separate endpoint or control for carousels - X treats multi-image tweets as a standard post with additional media. Simply include 2 to 4 IMAGE items in mediaItems, each with its own sortOrder value. PostFast uploads them in order and posts them as a single tweet.
Note that X does not support mixing images with video in the same post, and does not support more than 4 images. Video carousels are not a supported pattern on X.
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": "Behind the scenes: 4 steps we shipped this week to cut API latency by 40%. Full write-up in the replies.",
"mediaItems": [
{
"key": "image/d4e5f6a7-b8c9-0123-4567-890123abcdef.jpg",
"type": "IMAGE",
"sortOrder": 0
},
{
"key": "image/e5f6a7b8-c9d0-1234-5678-901234bcdef1.jpg",
"type": "IMAGE",
"sortOrder": 1
},
{
"key": "image/f6a7b8c9-d0e1-2345-6789-012345cdef12.jpg",
"type": "IMAGE",
"sortOrder": 2
},
{
"key": "image/a7b8c9d0-e1f2-3456-7890-123456def123.jpg",
"type": "IMAGE",
"sortOrder": 3
}
],
"scheduledAt": "2026-05-01T15:00:00.000Z",
"socialMediaId": "aa1a3044-98aa-07b2-b493-221232117009"
}
],
"controls": {}
})
});
const data = await response.json();
Did You Know?
Tips
Use sortOrder 0, 1, 2, 3 to control the display order - the lowest value appears first
Lead with your strongest image - it's the one that shows largest in the feed grid preview
Carousels work well for step-by-step content: each image = one step
Upload images in advance via /file/get-signed-upload-urls, then reference the S3 keys in mediaItems
A carousel counts as one post against your plan's X daily limit - same weight as a single-image tweet
Schedule multi-image tweets across your X accounts
Common Pitfalls
X hard-caps multi-image tweets at 4. A 5th+ IMAGE item in mediaItems will cause the post to fail.
Carousels are image-only. Adding a VIDEO item to an IMAGE carousel will cause the post to fail - X does not allow mixed media in a single tweet.
Every media item needs a unique sortOrder. Duplicates or gaps can produce unpredictable ordering in the published carousel.
A 4-image carousel is one tweet with 4 images. A thread is 4 separate tweets replying to each other. PostFast supports the carousel pattern via the API; chained threads are not exposed.
Frequently Asked Questions
How do I create a multi-image tweet?
Include 2 to 4 IMAGE items in the mediaItems array, each with a unique sortOrder value (0, 1, 2, 3). PostFast attaches them all to the same tweet as a carousel.
Can I include a video alongside images?
No. X does not allow mixing images and video in a single post. Carousels are image-only - if you have video content, schedule it as a separate tweet.
How does sortOrder affect the display?
Images are rendered in ascending sortOrder - the item with sortOrder 0 appears first, then 1, 2, 3. The first image is the largest in the feed grid preview.