How to Schedule Threads Carousels via API
Create multi-image carousel posts on Threads using the PostFast API. Schedule up to 10 images in a single swipeable post.
Threads carousels let you share multiple images and videos in a single swipeable post, perfect for tutorials, product showcases, or storytelling. Using the PostFast API, you can schedule carousel posts with 2-10 items.
To create a carousel, include multiple IMAGE or VIDEO items in your mediaItems array with sequential sortOrder values. Threads will automatically display them as a swipeable carousel.
Unlike single-image posts, carousels encourage users to spend more time engaging with your content, often resulting in higher engagement rates and better reach on the platform. A carousel takes one topic, like any Threads post, set with the threadsTopicTag control.
API Parameters
| Parameter | Type | Description |
|---|---|---|
threadsTopicTag | string | The post's topic on Threads: one topic per post, 1-50 characters, with no "." or "&". It shows as the post's topic in Threads, and if the text also contains a #hashtag, the topic wins and the hashtag stays plain text. Like every control, it applies to every post in the request. |
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": "5 design principles every developer should know (swipe through)\n\n1. Whitespace is your friend\n2. Limit your color palette\n3. Typography matters more than you think\n4. Consistency builds trust\n5. Less is almost always more\n\nWhich one do you struggle with most?",
"mediaItems": [
{
"key": "image/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"type": "IMAGE",
"sortOrder": 0
},
{
"key": "image/b2c3d4e5-f6a7-8901-bcde-f12345678901.jpg",
"type": "IMAGE",
"sortOrder": 1
},
{
"key": "image/c3d4e5f6-a7b8-9012-cdef-012345678912.jpg",
"type": "IMAGE",
"sortOrder": 2
},
{
"key": "image/d4e5f6a7-b8c9-0123-def0-123456789023.jpg",
"type": "IMAGE",
"sortOrder": 3
},
{
"key": "image/e5f6a7b8-c9d0-1234-ef01-234567890134.jpg",
"type": "IMAGE",
"sortOrder": 4
}
],
"scheduledAt": "2025-01-31T10:00:00.000Z",
"socialMediaId": "99012833-a6df-75b8-e150-889099883005"
}
],
"controls": {
"threadsTopicTag": "Design"
}
})
});
const data = await response.json();
Did You Know?
Tips
Use the first image as a hook - it's what users see before swiping
Number your slides in the caption to encourage swiping (e.g., 'Swipe for all 5 tips')
Keep a consistent visual style across all carousel images for a professional look
End with a call-to-action slide to drive engagement or follows
Carousels perform well for educational content, tutorials, and listicles
Schedule carousels to Threads and 7 other platforms from one API
Common Pitfalls
If you only include 1 image, it will be a regular image post, not a carousel. Include at least 2 images.
Ensure sortOrder values are sequential starting from 0. Gaps or duplicates may cause unexpected image ordering.
More than 10 items will cause an error. Split larger sets into separate posts.
While Threads accepts various sizes, using consistent dimensions across all carousel images provides a better viewing experience.
Frequently Asked Questions
What's the maximum number of images in a Threads carousel?
Up to 10 items: images, videos or both. You need at least 2 for it to be treated as a carousel (1 item = regular post).
Can I mix images and videos in a Threads carousel?
Yes. Add IMAGE and VIDEO items to the same mediaItems array, up to 10 in total, and use sortOrder to set their order.
How do I control the order of images in the carousel?
Use the sortOrder field in each mediaItem. Set values starting from 0 in the order you want images to appear (0 = first, 1 = second, etc.).