Threads Posts

You can use the Threads API to publish image, video, text, or carousel posts.

This document covers:

• Single Thread Posts
• Carousel Posts
• Topic Tags, Links, and GIFs
• Media Specifications

Single Thread Posts

Publishing a single image, video, or text post is a two-step process:

1. Create a media container with text only or with an image or video hosted on your public server with optional text using the POST /{threads-user-id}/threads endpoint.
2. Publish the media container using the POST /{threads-user-id}/threads_publish endpoint.

Limitations

• Text posts are limited to 500 characters.
• Emojis are counted as the number of UTF-8 bytes.

Step 1: Create a Threads media container

Use the POST /{threads-user-id}/threads endpoint to create a Threads media container.

Parameters

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

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

Example Response

{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

Step 2: Publish the Threads media container

Use the POST /{threads-user-id}/threads_publish endpoint to publish the media 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.

Parameters

Example Request

curl -i -X POST \
  -d "creation_id=<MEDIA_CONTAINER_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish"

Example Response

{
  "id": "<THREADS_MEDIA_ID>"
}

Carousel Posts

You may publish up to 20 images, videos, or a mix of the two in a carousel post. Publishing carousels is a three-step process:

1. Create the individual media containers for each image and video that should appear in the carousel using the POST /{threads-user-id}/threads endpoint.
2. Create a single carousel container to contain the media containers using the POST /{threads-user-id}/threads endpoint.
3. Publish the carousel container using the POST /{threads-user-id}/threads_publish endpoint.

Note: Carousel posts count as a single post against a profile's rate limit.

Limitations

• Carousels are limited to 20 images, videos, or a mix of the two.
• Carousels require a minimum of two children.

Step 1: Create an media container

Use the POST /{threads-user-id}/threads endpoint to create a media container for each of the images and/or videos that will appear in the carousel.

Parameters

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

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"

Example Response

{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

If the operation is successful, the API will return an media container ID, which can be used when creating the carousel container.

Repeat this process for each image and/or video that will appear in the carousel.

Step 2: Create a carousel container

Use the POST /{threads-user-id}/threads endpoint to create a carousel container.

Parameters

Refer to the POST /{threads-user-id}/threads endpoint reference for additional supported parameters.

Example Request

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"

Example Response

{
  "id": "<THREADS_CAROUSEL_CONTAINER_ID>"
}

Step 3: Publish the carousel container

Use the POST /{threads-user-id}/threads_publish endpoint to publish a carousel post.

Note: Profiles are limited to 250 published posts within a 24-hour period. Publishing a carousel counts as a single post.

Parameters

Example Request

curl -i -X POST \
  -d "creation_id=<MEDIA_CONTAINER_ID>" \
  -d "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publish"

Example Response

{
  "id": "<THREADS_MEDIA_ID>"
}

If the operation is successful, the API will return the carousel album's Threads media ID.

Topic Tags, Links, and GIFs

Topics and links appear in posts in such a way as to encourage engagement.

Topic Tags

Topics make posts more social by allowing central topics of discussion. You can include a topic in a post either by using the topic_tag parameter or by including a tag within the text of a post.

Using the topic_tag parameter

Note: Topic tags must be at least 1 character and no more than 50 characters long. The following characters are not allowed:

• Periods (.)
• Ampersands (&)

Example request

curl -i -X POST \
  -d "media_type=TEXT" \
  -d "text=<Text>" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "topic_tag=<TAG>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Using an in-text topic tag

A topic can also be attached to a post by including it in-line within the text of the post. Only one topic 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 topic to a post using an in-text tag:

• Valid tags start with a hash sign (#).
• The text is also configured in the app without the hash sign.
• Topic must be at least 1 character and no more than 50 characters long.
• Whole numbers that are preceded by a hash sign (i.e., #1) will not be converted into a tag. This is because it is assumed that # is signifying a number sign in this scenario.

• The following characters are not allowed when using in-text tags with the Threads API, so any in-text tag that starts with a hash sign will end just before these characters:

  • Spaces, Tabs, New Line Characters
  • Periods (.)
  • Ampersands (&)
  • At Signs (@)
  • Exclamation Marks (!)
  • Question Marks (?)
  • Commas (,)
  • Semi-Colons (;)
  • Colons (:)

Links

To attach a link to your post, use the link_attachment parameter when creating a media container. If no link_attachment parameter is provided, then 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.

Limitations

• This feature is only available for text-only posts. It will not work with image, video, or carousel posts.

Publishing

Links can be attached when making an API call to the POST /{threads-user-id}/threads endpoint to create a media container.

Example Request

curl -i -X POST \  
  -d "media_type=TEXT" \
  -d "text=<TEXT>" \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "link_attachment=<URL> \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Example Response

{
  "id": "<THREADS_MEDIA_CONTAINER_ID>"
}

The request above creates a Threads media container that, once published, will attach a link preview to your media.

Media Retrieval

The value for the link_attachment URL can be retrieved by making a request to the GET /threads or GET /{threads_media_id} endpoint to retrieve media object(s).

Example Request

curl -s -X GET \ 
"https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,link_attachment_url&access_token=<ACCESS_TOKEN>"

Example Response

{
   "id": "<THREADS_MEDIA_ID>",
   "link_attachment_url": "<LINK_ATTACHMENT_URL>",
}

GIFs

GIFs make posts more engaging by allowing users to express reactions, emotions, or ideas visually.

Limitations

• This feature is only available for text-only posts. It will not work on image, video, or carousel posts.
• Tenor is currently the only available GIF provider.

Publishing

GIFS can be attached when making an API call to the POST /{threads-user-id}/threads endpoint to create a media container.

Example request

curl -i -X POST \  
  -d "media_type=TEXT" \
  -d "text=<Text> \
  -d "access_token=<ACCESS_TOKEN>" \
  -d "gif_attachment={"gif_id":"<GIF_ID>","provider":"TENOR"}" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads"

Note: The value of the id field you receive from the Tenor API response should be used as the <GIF_ID> in the API call.

Example response

{
 "id": "<THREADS_MEDIA_ID>"
}

The request above creates a Threads media container that, once published, will attach a GIF to your media.

Media Specifications

Learn More

• Reposts
• Quote Posts
• Polls
• Spoilers
• Text Attachments