Meta Sets the Instagram API alt_text Character Limit at 1,000

What is the Instagram API alt_text character limit?

Meta's own reference sets the Instagram API alt_text character limit at 1,000 characters, and restricts the field to still images. The parameter description on the media creation endpoint reads, word for word: "Alternative text, up to 1000 character, for an image. Only supported on a single image or image media in a carousel. Reels and stories are not supported."

One sentence, three separate rules. The ceiling is 1,000. The field belongs to an image, either standing alone or sitting inside a carousel. Reels and stories are excluded by name. Everything else people believe about Instagram alt text comes from somewhere other than that sentence.

The field lives on the container creation call:

POST https://graph.facebook.com/v25.0/<IG_ID>/media
  ?image_url=https://example.com/photo.jpg
  &alt_text=A%20hand-drawn%20site%20plan%20pinned%20to%20a%20studio%20wall
  &caption=Week%20four
  &access_token=<TOKEN>

You pass alt_text when you create the container, not when you publish it. The publish step, POST /<IG_ID>/media_publish, takes a creation_id and nothing else that touches accessibility. Miss the field on the container and there is no second chance in the same flow.

Meta dates the feature precisely. The content publishing guide states: "On March 24, 2025, we introduced the new alt_text field for image posts on the /<INSTAGRAM_PROFESSIONAL_ACCOUNT_ID>/media endpoint. Reels and stories are not supported." Anything written about Instagram's publishing API before that date describes a world with no programmatic alt text at all.

Before and after March 24, 2025

Before

• No alt_text field on the publishing API
• No programmatic way to set image descriptions

After

• alt_text field live on the media endpoint
• Up to 1,000 characters, images only

Which Instagram media types accept alt_text?

Only images. Here is the full grid, drawn from the parameter description and the media type list on the same reference page.

Container	alt_text accepted	What the documentation says
Single image (no media_type needed)	Yes	"Only supported on a single image"
Image inside a carousel (is_carousel_item=true)	Yes	"or image media in a carousel"
Carousel container (media_type=CAROUSEL)	No	The field describes an image, and the container holds children, not pixels
media_type=REELS	No	"Reels and stories are not supported"
media_type=STORIES	No	"Reels and stories are not supported"
Video	Not listed	The parameter is scoped "for an image"; no video container is documented as taking it

Read the last row carefully, because it is the one that gets misquoted. Meta does not write the words "video is not supported." It writes that the parameter is alternative text "for an image," and it names reels and stories as the exclusions. This endpoint publishes standalone video as REELS, which the sentence rules out directly. The practical outcome matches the shorthand everyone repeats, but the documentation arrives there by scope rather than by prohibition, and a spec page should say which.

Why is the app's number different from the API's number?

Meta's developer documentation publishes exactly one alt text limit: 1,000 characters, on the alt_text parameter. It publishes no limit for the alt text box inside the Instagram app.

This is the gap worth naming. Accessibility guides and social media blogs circulate a much shorter in-app figure, quoted with no link back to Meta. That figure appears nowhere in Meta's developer documentation, and it does not appear in the changelog either, which carries no alt_text entry at all. So this page does not repeat it. If you need to know how many characters the app composer will hold, the answer available from Meta is that Meta does not say.

What you get instead is a hard number for the one surface that documents itself. If your alt text goes through the API, 1,000 characters is the budget, and it is the only budget Meta commits to in writing. The constraint people plan around turns out not to be the one that exists.

How does the alt_text limit compare to the caption limit?

The same reference page documents both, so the comparison is apples to apples.

Field	Ceiling	Extra rules
alt_text	1,000 characters	Images only. No reels, no stories
caption	2,200 characters	Maximum 30 hashtags and 20 @ tags

Meta's caption description is explicit about the tag counts: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." The alt_text description carries no equivalent sub-rules. No hashtag cap is documented, no mention cap, no markup handling. It is a plain text field with a ceiling.

That asymmetry matters when you build a composer. A caption validator needs three counters. An alt text validator needs one, plus a check on which media type the user picked.

Where does alt_text go in a carousel post?

On each child container, one at a time. You build a carousel in two stages. First a container per item with is_carousel_item=true, then the parent with media_type=CAROUSEL and a children array of those IDs. Meta's note on is_carousel_item reads: "Applies only to images and video. Set to true. Indicates image or video appears in a carousel."

Alt text attaches at the child level, which follows from the parameter description covering "image media in a carousel." Ten slides means ten separate alt_text values, written for ten separate images. There is no parent-level field that describes the set, and no way to write one string that covers the whole swipe. Teams that batch carousels through a scheduling tool for Instagram hit this immediately. The alt text work scales with slide count, not with post count.

Video children in a carousel inherit the same scope problem as standalone video. The child container accepts is_carousel_item, but alt_text is documented for image media.

What happens to alt text on Reels and Stories?

Nothing, because the field does not exist there. Send alt_text on a REELS or STORIES container and you are sending a parameter the endpoint does not document. There is no partial support, no truncation, no fallback to the caption.

This leaves a real hole for anyone publishing video at volume through the Instagram posting API. The accessible description has to live somewhere else, which in practice means the caption, on-screen text, or captions burned into the video itself. Those are editorial choices, not API fields, and they belong in whatever content calendar your team already works from.

How do you actually use 1,000 characters?

Most alt text does not need them, and length is not the goal. The value of knowing the real ceiling is that it removes the wrong reason to be terse. When a photograph carries a chart, a menu, a price list, a schedule, or dense on-image text, you are no longer choosing between a description and a summary. You have room for both.

For a dense image, lead with the subject and what it is doing, then the setting, then any text visible in the frame transcribed rather than paraphrased. Skip "image of" and "photo of," since assistive technology already announces the element. Keep the brand voice in the caption, where an AI caption writer does that job, and keep the alt text describing what is there.

The one number to design around is 1,000, per container, images only. Everything else about Instagram alt text is either editorial judgment or an undocumented app behaviour that Meta has not committed to in writing.

Frequently Asked Questions

What is the maximum length of alt_text on the Instagram API?

1,000 characters. Meta's reference for the media creation endpoint describes the parameter as "Alternative text, up to 1000 character, for an image," and that is the only alt text ceiling published in the developer documentation.

Does the Instagram API support alt_text on Reels?

No. Meta's documentation states plainly that "Reels and stories are not supported" for the alt_text field, both in the parameter description and in the content publishing guide's launch note.

Can you set alt text on each slide of an Instagram carousel?

Yes, on each child container. The parameter description covers "image media in a carousel," so you pass alt_text alongside is_carousel_item=true when creating each image child, before assembling the parent CAROUSEL container.

Is the Instagram app's alt text limit the same as the API's?

Meta's developer documentation does not publish a character limit for the alt text field in the Instagram app, so the two cannot be compared from a citable source. The 1,000 character figure applies to the alt_text API parameter.

When did Instagram add alt_text to its publishing API?

March 24, 2025. The content publishing guide records the launch date and scopes it to image posts on the /<INSTAGRAM_PROFESSIONAL_ACCOUNT_ID>/media endpoint.

Does alt_text count toward the Instagram caption limit?

No. They are separate parameters with separate ceilings on the same container: caption allows 2,200 characters with a maximum of 30 hashtags and 20 @ tags, while alt_text allows 1,000 characters with no documented sub-rules.

Can you add alt_text to a standalone video post through the API?

Video is not listed among the containers that accept alt_text. The parameter description scopes the field "for an image," and this endpoint publishes standalone video through a REELS container, one of the two types the documentation excludes by name.

At what step in the publishing flow do you set alt_text?

You pass alt_text when you create the container with the initial POST to /<IG_ID>/media, not at the publish step. The media_publish call only takes a creation_id, so there is no second chance to attach alt text once the container exists without it.

What happens if you send alt_text on a Reels or Stories container anyway?

Nothing useful, because the endpoint does not document the field for those container types. Meta's reference describes no partial support, no truncation, and no fallback that copies the text into the caption.

Does the alt_text field carry sub-rules the way the caption field does?

It doesn't. The caption parameter comes with a documented cap of 30 hashtags and 20 @ tags alongside its character limit, while the alt_text description lists none of that, just the 1,000-character ceiling and the image-only scope.