Spoilers
Updated: Oct 13, 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:
Permissions
Publishing posts with spoilers requires the following permissions:
threads_basic— Required for making any calls to all Threads API endpoints.threads_content_publish— Required for Threads publishing endpoints only.
If your app has not been approved for advanced access for the
threads_content_publish permission, you can only post on behalf of Threads testers on your app. After your app is published and approved, you can post on behalf of any Threads user who grants your app the permission.Limitations
- Media spoilers only work with a
media_typeofIMAGE,VIDEO, orCAROUSEL. - 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
| Whether the media should be a spoiler. 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_entitiesparameter. - If a spoiler needs to be added to the media object in the post, use the
is_spoiler_mediaparameter. - If a spoiler needs to be added to the text and media objects in the post, use both the
text_entitiesandis_spoiler_mediaparameters.
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_entitiesparameter. - If a spoiler needs to be added to the media object in the post, use the
is_spoiler_mediaparameter. - If a spoiler needs to be added to the text and media objects in the post, use both the
text_entitiesandis_spoiler_mediaparameters.
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.