The Threads API is currently being tested in a limited Beta. This documentation is shared to allow developers to familiarize themselves with the API ahead of general availability, and is subject to change. Find out more in this blog post.
You can use the Threads API to publish image, video, text, or carousel posts.
This document covers:
Publishing a single image, video, or text post is a two-step process:
POST /{ig-user-id}/threads endpoint to create a media container using an image or video hosted on your public server and optional text. Alternatively, use this endpoint to create a media container with text only.POST /{ig-user-id}/threads_publish endpoint to publish the container.Use the POST /{ig-user-id}/threads endpoint to create a Threads media container.
The following parameters are required. Refer to the POST /{ig-user-id}/threads endpoint reference for additional supported parameters.
is_carousel_item — Default value is false for single thread posts. Indicates an image or video that will appear in a carousel.image_url — (For images only.) The path to the image. We will cURL your image using the URL provided so it must be on a public server.media_type — Set to either TEXT, IMAGE, or VIDEO. Indicates the current media type. Note: Type CAROUSEL is not available for single thread posts.video_url — (For videos only.) Path to the video. We will cURL your video using the URL provided so it must be on a public server.text — The text associated with the post. The first URL included in the text field will be used as the link preview for the post. For text-only posts, this parameter is required.
curl -i -X POST \
"https://graph.instagram.com/v20.0/<IG_USER_ID>/threads?media_type=IMAGE&image_url=https://www.example.com/images/bronz-fonz.jpg&text=#BronzFonz&access_token=<ACCESS_TOKEN>"
{
"id": "1234567" // Threads Media Container ID
}
Use the POST /{ig-user-id}/threads_publish endpoint to publish the container ID returned in the previous step. It is recommended to wait on average 30 seconds before publishing a Threads media container to give our server enough time to fully process the upload. See the media container status endpoint for more details.
creation_id — Identifier of the Threads media container created from the /threads endpoint.
curl -i -X POST \
"https://graph.instagram.com/v20.0/<IG_USER_ID>/threads_publish?creation_id=<MEDIA_CONTAINER_ID>&access_token=<ACCESS_TOKEN>"
{
"id": "1234567" // Threads Media ID
}
You may publish up to 10 images, videos, or a mix of the two in a carousel post. Publishing carousels is a three-step process:
POST /{ig-user-id}/threads endpoint to create individual item containers for each image and video that will appear in the carousel.POST /{ig-user-id}/threads endpoint again to create a single carousel container for the items.POST /{ig-user-id}/threads_publish endpoint to publish the carousel container.Carousel posts count as a single post against the account's rate limit.
Use the POST /{ig-user-id}/threads endpoint to create an item container for the image or video that will appear in a carousel.
The following parameters are required. Refer to the POST /{ig-user-id}/threads endpoint reference for additional supported parameters.
is_carousel_item — Set to true. Indicates that the image or video will appear in a carousel.image_url — (For images only.) The path to the image. We will cURL your image using the passed in URL so it must be on a public server.media_type — Set to IMAGE or VIDEO. Indicates that the media is an image or a video.video_url — (For videos only.) Path to the video. We will cURL your video using the passed in URL so it must be on a public server.Note: While the text field is optional for carousel posts, the first URL included in the text field will be used as the link preview for the post.
If the operation is successful, the API will return an item container ID, which can be used when creating the carousel container.
Repeat this process for each image or video that should appear in the carousel.
curl -i -X POST \
"https://graph.instagram.com/v20.0/<IG_USER_ID>/threads?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=<ACCESS_TOKEN>"
{
"id": "1234567"
}
Use the POST /{ig-user-id}/threads endpoint to create a carousel container.
The following parameters are required. Refer to the POST /{ig-user-id}/threads endpoint reference for additional supported parameters.
media_type — Set to CAROUSEL. Indicates that the container is for a carousel.children — A comma-separated list of up to 10 container IDs of each image and/or video that should appear in the published carousel. Carousels can have at least 2 and up to 10 total images or videos or a mix of the two.text— (Optional.) The text associated with the post.
curl -i -X POST \
"https://graph.instagram.com/v20.0/<IG_USER_ID>/threads?media_type=CAROUSEL&children=<MEDIA_ID_1>,<MEDIA_ID_2>,<MEDIA_ID_3>&access_token=<ACCESS_TOKEN>"
{
"id": "1234567"
}
Use the POST /{ig-user-id}/threads_publish endpoint to publish a carousel post. Accounts are limited to 250 published posts within a 24-hour period. Publishing a carousel counts as a single post.
The following parameters are required.
creation_id — The carousel container ID.If the operation is successful, the API will return a carousel album's Threads Media ID.
curl -i -X POST \
"https://graph.instagram.com/v20.0/<IG_USER_ID>/threads_publish?creation_id=<MEDIA_CONTAINER_ID>&access_token=<ACCESS_TOKEN>"
{
"id": "1234567" // Threads Media ID
}
Tags and links appear in posts in such a way as to encourage engagement.
Tags make posts more social by allowing central topics of discussion. Only one tag is allowed per post, so the first valid tag included in a post of any type (text-only, image, video, carousel) via the API is treated as the tag for that post.
Information to keep in mind when adding a tag to a post:
The first link made in a text-only post via the API is configured as the link attachment, which displays as a preview card, to make it easier to engage with and click on.