Spoilers

Updated: Jul 2, 2026

Copy for LLM

You can create posts with spoilers using the Threads API. Spoilers can be added to text in a post or can be used with media types like images and videos.

This document covers:

Text and Media Spoilers

Single Threads Posts with Spoilers

Carousel Posts with Spoilers

Limitations

Media spoilers only work with a media_type of IMAGE, VIDEO, or CAROUSEL.

The maximum number of text spoiler entities per post is limited to 10.

Text and media spoilers

Create a spoiler within a text field

To create a text post with a spoiler, use the text_entities parameter. This parameter takes a list of entity_type, offset, and length values. Each entry represents part of the text post where the API applies the spoiler.

Parameters

Name	Description
`entity_type` string	Indicates the kind of `entity_type`. Values: `SPOILER`, `spoiler`
`offset` int	The starting position of the spoiler. Values: Positive whole numbers, such as 1 and 2.
`length` int	The length of the spoiler text starting from the `offset` position. Values: Positive whole numbers, such as 1 and 2.

Create a media spoiler

To create a post with spoilers for media objects such as an image or video, use the is_spoiler_media parameter.

Parameters

Name	Description
`is_spoiler_media` Boolean	Indicates if the media should be a spoiler or not. Values: `true`, `false`

Single Threads posts

Step 1: Create a Threads media container

Spoilers for single Threads posts need to be provided during the Threads media container creation phase.

If a spoiler needs to be added in the text field of the post, use the text_entities parameter.

If a spoiler needs to be added to the media object in the post, use the is_spoiler_media parameter.

If a spoiler needs to be added to the text and media objects in the post, use both the text_entities and is_spoiler_media parameters.

Example requests

Spoiler only in the text field

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=TEXT" \
  -d "text=<TEXT>" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.com/v1.0/<THREADS_USER_ID>/threads"

Spoiler only for a media object (image/video)

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=IMAGE" \
  -d "image_url=<IMAGE_URL>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
"https://graph.threads.com/v1.0/<THREADS_USER_ID>/threads"

Spoiler for both text and a media object (image/video)

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=IMAGE" \
  -d "image_url=<IMAGE_URL>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.com/v1.0/<THREADS_USER_ID>/threads"

Response

If the API call is successful, the Threads media container ID will be returned.

Step 2: Publish the Threads media container

You can now publish using the returned Threads media container ID to create your single Threads post with spoilers.

Threads carousel posts

Step 1: Create a Threads media container

Create a Threads media container for each of the items to be included in the carousel.

Step 2: Create the carousel container

Spoilers for Threads carousel posts need to be provided during the carousel container creation phase.

If a spoiler needs to be added in the text field of the post, use the text_entities parameter.

If a spoiler needs to be added to the media object in the post, use the is_spoiler_media parameter.

If a spoiler needs to be added to the text and media objects in the post, use both the text_entities and is_spoiler_media parameters.

Note: If is_spoiler_media is set to true all attached media such as images and videos will be marked as spoilers.

Example requests

Spoiler only in the text field

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>" \
  -d "text=<TEXT>" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.com/v1.0/<THREADS_USER_ID>/threads"

Spoiler only for a media object (image/video)

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

Spoiler for both text and a media object (image/video)

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "media_type=CAROUSEL" \
  -d "children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>" \
  -d "text=<TEXT>" \
  -d "is_spoiler_media=true" \
  -d "text_entities=[
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 0,
      "length": 2
    },
    {
      "entity_type": "SPOILER",
      "text": "spoiler",
      "offset": 2,
      "length": 7
    }
  ]" \
"https://graph.threads.com/v1.0/<THREADS_USER_ID>/threads"

Response

If the API call is successful, the Threads media container ID will be returned.

Step 3: Publish the Threads media container

You can now publish using the returned Threads media container ID to create your Threads carousel post with spoilers.

Learn more

Posts

Retrieve User Posts