How the Threads API Carousel Maximum Items Cap Works

What is the Threads API carousel maximum items limit?

Meta puts the Threads API carousel maximum items ceiling at 20 children, with a floor of 2, and states the pair four times across two pages. The posts guide opens its carousel section with "You may publish up to 20 images, videos, or a mix of the two in a carousel post", then lists the rule twice more under Limitations: "Carousels are limited to 20 images, videos, or a mix of the two" and "Carousels require a minimum of two children."

The overview page states the same thing as one line under Other Limitations: "Carousel posts must have a maximum of 20 children and a minimum of 2 children." The children parameter description repeats it a fourth time: "Carousels must have at least 2 and no more than 20 total images, videos, or a mix of the two."

Four statements, one number. That level of agreement is unusual in Meta's publishing documentation and it means an integration can hardcode the bounds check without worrying about which page is stale.

When did the Threads carousel cap become 20?

On September 19, 2024, and Meta logged the change in the Threads changelog: "Carousel posts are now allowed up to 20 images, videos, or a mix of the two." Before that entry the ceiling was 10, matching Instagram.

That date matters when auditing older code. A hardcoded 10 is the first thing to look for in any Threads integration written before September 2024 or ported from an Instagram publishing library, because it silently splits a 16-image set into two posts that each burn a slot against the daily publishing quota.

How does the per-item container flow work?

Publishing a Threads carousel takes three calls, one more than a single post. Meta describes it as creating "the individual media containers for each image and video", then "a single carousel container to contain the media containers", then the publish.

Step 1 creates one container per item. The distinguishing parameter is is_carousel_item=true, and media_type accepts IMAGE or VIDEO here:

curl -i -X POST \
  -d "image_url=<IMAGE_URL>" \
  -d "is_carousel_item=true" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Each call returns a container ID. Repeat it for every item, up to 20.

Step 2 creates the carousel container itself, with media_type=CAROUSEL and a comma-separated children list of the IDs from step 1. The post's text belongs on this call, not on the individual items:

curl -i -X POST \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>,..." \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Step 3 publishes the carousel container by passing its ID as creation_id to POST /{threads-user-id}/threads_publish, which returns the published media ID. Meta advises waiting "on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload", and for video items recommends polling GET /{threads-container-id}?fields=status,error_message "once per minute, for no more than 5 minutes".

Where do Meta's own pages disagree on carousel items?

is_carousel_item gets two different classifications on two live pages. The posts guide marks it "Required" in the parameter table for single thread posts, with values true and false (default). The POST /{threads-user-id}/threads reference marks the same parameter "Optional", with values true and false (default).

Since both pages agree the default is false, the reference is the coherent one: a parameter with a default cannot be required. The same table in the carousel section also carries a note copied from the single-post table, "CAROUSEL is not available for single thread posts", which is true but has nothing to do with a carousel item. Read the parameter tables for the values and the reference for whether a field is mandatory.

What does a too-large carousel return?

Meta documents no error for a children list that breaks the bounds. The Threads API Reference index lists nine endpoint pages and no error codes page, and developers.facebook.com/documentation/threads/reference/error-codes does not resolve. The troubleshooting page covers only two things: container status values and media processing failures.

Every one of those describes a single media file, not a malformed children list. The only publish-path error code Meta names anywhere in the Threads documentation is THREADS_API__LINK_LIMIT_EXCEEDED, which fires when a post carries more than five links.

So there is nothing to catch by name. Validate the length of children before the step 2 call, reject anything under 2 or over 20 locally, and treat whatever the API returns for an out-of-bounds list as undocumented behaviour that can change without a changelog entry.

Does a carousel count as one post or as twenty?

One. Meta says it in both places the rule could be looked for: "Carousel posts count as a single post against a profile's rate limit" in the carousel section, and "Publishing a carousel counts as a single post" in the note above Step 3.

That makes the carousel the biggest lever anyone has on Threads publishing volume. A profile capped at 250 API-published posts within a 24-hour moving period can move 5,000 pieces of media if every publish is a full 20-item carousel, against 250 if each post carries one image. Twenty single posts cost twenty slots; the same twenty images as one carousel cost one.

How does the Threads carousel compare with Instagram's?

Both run on Meta infrastructure and neither ceiling matches the other. Instagram's content publishing guide states "Carousels are limited to 10 images, videos, or a mix of the two", half the Threads number, and its publishing quota is lower too.

Cross-posting the same set to both therefore needs a split rule, since an 18-image Threads carousel does not fit an Instagram post. The Instagram side of that arithmetic, including the second post-count sentence Meta leaves unresolved on its own page, is covered in the Instagram API 100 posts per 24 hours limit.

What does each carousel item have to satisfy?

The 20-item ceiling is a count, not a size budget, and every child is validated on its own against the same media specifications that govern single posts. Images must be JPEG or PNG, 8 MB maximum, aspect ratio within 10:1, with a minimum width of 320 and a maximum of 1440 that Meta scales to automatically. Videos must be MOV or MP4, 1 GB maximum, 300 seconds maximum, 23 to 60 FPS, with a maximum of 1920 horizontal pixels.

A single oversized child fails its own container at step 1, which means the carousel container never gets built. Validating media before the first call is cheaper than discovering at step 2 that one of nineteen IDs is missing, a habit that applies to carousel posts on every network.

The post text has its own separate ceiling of 500 characters on the carousel container, governed by the same rules covered in how the Threads API 500 character limit treats topic_tag.

Frequently asked questions

Can a Threads carousel mix images and videos?

Yes. Meta's wording is "20 images, videos, or a mix of the two" on every page that states the limit, so a carousel can hold any combination as long as the total stays between 2 and 20 and each item meets its own media specification.

What is the minimum number of items in a Threads carousel?

Two. Meta states "Carousels require a minimum of two children" in the posts guide and repeats it on the overview page as "a minimum of 2 children". A single-item carousel is not a valid container, so publish one image as a normal IMAGE post instead.

Does a 20-item carousel use 20 slots of the daily publishing quota?

No. Meta states that "Carousel posts count as a single post against a profile's rate limit", so a full 20-item carousel spends one of the 250 publishes available in a 24-hour moving period.

Where does the text of a carousel post go?

On the carousel container created in step 2, where text is listed as an optional parameter alongside media_type=CAROUSEL and children. The individual item containers in step 1 also accept text, and Meta never says what that value does on a carousel item.

Does creating carousel item containers count against any quota?

Meta enforces the publishing limit "on the POST /{threads-user-id}/threads_publish endpoint", which is step 3, so the item containers in step 1 and the carousel container in step 2 do not spend publishing quota. Containers do expire: an unpublished one returns EXPIRED, described as "The container was not published within 24 hours and has expired."

Where is the 20-item carousel limit documented?

In four places across two Meta pages. The posts guide at developers.facebook.com/documentation/threads/posts states it in the carousel introduction, in its Limitations list, and in the children parameter description; the overview page at developers.facebook.com/documentation/threads/overview states it under Other Limitations. The change from 10 to 20 is logged in the Threads changelog under September 19, 2024.

Is is_carousel_item a required parameter or an optional one?

Meta's own pages disagree. The posts guide marks it "Required" in the parameter table, while the POST /{threads-user-id}/threads reference marks the same parameter "Optional" with a default of false. Both pages agree on that default, so a parameter with a default value cannot be mandatory, and the reference page is the one to trust.

What file formats and size limits apply to a Threads carousel item?

Each item is validated against the same media specs as a single post, regardless of the carousel it sits in. Images must be JPEG or PNG, up to 8 MB, with an aspect ratio within 10:1. Videos must be MOV or MP4, up to 1 GB and 300 seconds, at 23 to 60 FPS.

How long should I wait before publishing a carousel container?

Meta recommends waiting about 30 seconds after creating a container before calling threads_publish, to give its servers time to process the upload. For video items, poll GET /{threads-container-id}?fields=status,error_message once a minute, for up to 5 minutes, before assuming the container is ready.

Is there a named error code for a carousel with too many or too few children?

None that Meta documents. The only publish-path error code named anywhere in the Threads docs is THREADS_API__LINK_LIMIT_EXCEEDED, which fires when a post carries more than five links. A children list outside the 2-to-20 range triggers no documented error, so validate the count locally before the step 2 call.