Threads API

Threads Reply Management API

The Threads Reply Management API allows you to read and manage replies to users' own Threads.

This guide will discuss how to:

Permissions

The Threads Reply Management API requires an appropriate access token and permissions based on the node you are targeting. While you are testing, you can easily generate tokens and grant your app permissions by using the Graph API Explorer.

  • threads_basic — Required for making any calls to all Threads API endpoints.
  • threads_manage_replies — Required for making POST calls to reply endpoints.
  • threads_read_replies — Required for making GET calls to reply endpoints.

Rate Limits

Threads profiles are limited to 1,000 API-published replies within a 24-hour moving period. You can retrieve a profile's current Threads replies rate limit usage with the GET /{threads-user-id}/threads_publishing_limit endpoint.

Note: This endpoint requires the threads_basic, threads_content_publish, and threads_manage_replies permissions.

Fields

NameDescription

reply_quota_usage

Threads reply publishing count over the last 24 hours.

reply_config

Threads reply publishing rate limit config object, which contains the quota_total and quota_duration fields.

Example Request

curl -s -X GET \
  "https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_publishing_limit?fields=reply_quota_usage,reply_config&access_token=<ACCESS_TOKEN>"

Example Response

{
  "data": [
    {
      "reply_quota_usage": 1,
      "reply_config": {
        "quota_total": 1000,
        "quota_duration": 86400
      }
    }
  ]
}

Retrieve the Replies to a Thread

There are two ways of retrieving a thread's replies: GET {media-id}/replies and GET {media-id}/conversation.

GET {media-id}/replies only returns the top-level replies under the Threads ID provided in the request, while GET {media-id}/conversation returns all replies, regardless of the depth, either in chronological or reverse chronological order.

Parameters

These parameters are for both GET {media-id}/replies and GET {media-id}/conversation.

NameDescription

reverse

true if replies should be sorted in reverse chronological order. false if replies should be sorted in chronological order.
Default: true

Fields

These fields are for both GET {media-id}/replies and GET {media-id}/conversation.

NameDescription

id (default)

The media's ID.

text

Represents text for a Threads reply. This is optional on image, video, and carousel replies.

username

Threads username who created the post.
Note: This only works for public users, your own user, and users that you follow.

permalink

Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation.
Note: This only works for public users, your own user, and users that you follow.

timestamp

The publish date and time of the post in ISO 8601 format.

media_product_type

Surface where the media is published. In the case of Threads, the value is THREADS.

media_type

The media type for a Threads reply will be one of these values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, or AUDIO.

media_url

The post’s media URL. This only shows for image, video, and carousel replies.

shortcode

Shortcode of the media.

thumbnail_url

URL of thumbnail. This only shows for Threads replies with video.

children

List of child posts. This only shows for carousel replies.

is_quote_post

Indicates if the media is a quoted reply made by another user.

has_replies

true if the Threads post or reply has replies that you can see.

root_post

Media ID of the top-level post or original thread in the reply tree.
Note: This only appears on replies.

replied_to

Media ID of the immediate parent of the reply.
Note: This only appears on replies.

is_reply

true if the Threads media is a reply. false if the Threads media is a top-level post.

is_reply_owned_by_me

true if your user is the owner of the Threads reply. false if another user is the owner of the Threads reply.
Note: This only appears on replies.

hide_status

Whether or not the reply is hidden.
Values: NOT_HUSHED, UNHUSHED, HIDDEN, COVERED, BLOCKED, RESTRICTED
Note: This only appears on replies.

reply_audience

Who can reply to your post.
Values: EVERYONE, ACCOUNTS_YOU_FOLLOW, MENTIONED_ONLY
Note: This only appears on top-level posts and replies that you own.

A Thread's Replies

Use {media-id}/replies to fetch a paginated list of all top-level replies.

This endpoint is applicable to the use cases that focus on the depth level of the replies. The endpoint returns the immediate replies of the requested Threads ID. has_replies indicates whether a Thread has nested replies or not and the field can be used to decide to chain further subsequent GET calls to retrieve replies located in the deeper levels.

Example Request

curl -s -X GET \
  "https://graph.threads.net/v1.0/<MEDIA_ID>/replies?fields=id,text,timestamp,media_product_type,media_type,media_url,shortcode,thumbnail_url,children,has_replies,root_post,replied_to,is_reply,hide_status&reverse=false&access_token=<ACCESS_TOKEN>"

Example Response

{
  "data": [
    {
      "id": "1234567890",
      "text": "First Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": true,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "NOT_HUSHED"
    },
    {
      "id": "1234567890",
      "text": "Second Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "HIDDEN"
    },
    {
      "id": "1234567890",
      "text": "Third Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "UNHUSHED"
    }
  ],
  "paging": {
    "cursors": {
      "before": "BEFORE_CURSOR",
      "after": "AFTER_CURSOR"
    }
  }
}

A Thread's Conversations

Use {media-id}/conversation to fetch a paginated and flattened list of all top-level and nested replies.

This endpoint is applicable to specific use cases that do not focus on the knowledge of the depthness of the replies. Note: This endpoint is only intended to be used on the root-level threads with replies.

Example Request

curl -s -X GET \
  "https://graph.threads.net/v1.0/<MEDIA_ID>/conversation?fields=id,text,timestamp,media_product_type,media_type,media_url,shortcode,thumbnail_url,children,has_replies,root_post,replied_to,is_reply,hide_status&reverse=false&access_token=<ACCESS_TOKEN>"

Example Response

{
  "data": [
    {
      "id": "1234567890",
      "text": "First Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": true,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "NOT_HUSHED"
    },
    {
      "id": "1234567890",
      "text": "Second Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "HIDDEN"
    },
    {
      "id": "1234567890",
      "text": "Third Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "UNHUSHED"
    },
    {
      "id": "1234567890",
      "text": "Nested Reply",
      "timestamp": "2024-01-01T18:20:00+0000",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "shortcode": "abcdefg",
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "hide_status": "NOT_HUSHED"
    }
  ],
  "paging": {
    "cursors": {
      "before": "BEFORE_CURSOR",
      "after": "AFTER_CURSOR"
    }
  }
}

Retrieve a List of All a User's Replies

Use the GET /{threads-user-id}/replies endpoint to return a paginated list of all replies created by a user.

Fields

Here's a list of fields that can be returned for each reply.

NameDescription

id (default)

The media's ID.

text

Represents text for a Threads reply. This is optional on image, video, and carousel replies.

username

Threads username who created the post.
Note: This only works for public users, your own user, and users that you follow.

permalink

Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation.
Note: This only works for public users, your own user, and users that you follow.

timestamp

The publish date and time of the post in ISO 8601 format.

media_product_type

Surface where the media is published. In the case of Threads, the value is THREADS.

media_type

The media type for a Threads reply will be one of these values: TEXT_POST, IMAGE, VIDEO, CAROUSEL_ALBUM, or AUDIO.

media_url

The post’s media URL. This only shows for image, video, and carousel replies.

shortcode

Shortcode of the media.

thumbnail_url

URL of thumbnail. This only shows for Threads replies with video.

children

List of child posts. This only shows for carousel replies.

is_quote_post

Indicates if the media is a quoted reply made by another user.

has_replies

true if the Threads post or reply has replies that you can see.

root_post

Media ID of the top-level post or original thread in the reply tree.
Note: This only appears on replies.

replied_to

Media ID of the immediate parent of the reply.
Note: This only appears on replies.

is_reply

true if the Threads media is a reply. false if the Threads media is a top-level post.

is_reply_owned_by_me

true if your user is the owner of the Threads reply. false if another user is the owner of the Threads reply.
Note: This only appears on replies.

reply_audience

Who can reply to your post.
Values: EVERYONE, ACCOUNTS_YOU_FOLLOW, MENTIONED_ONLY
Note: This only appears on top-level posts and replies that you own.

Example Request

curl -s -X GET \
  "https://graph.threads.net/v1.0/me/replies?fields=id,media_product_type,media_type,media_url,permalink,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post,has_replies,root_post,replied_to,is_reply,is_reply_owned_by_me,reply_audience&since=2023-10-15&until=2023-11-18&limit=1&access_token=<ACCESS_TOKEN>"

Examples Response

{
  "data": [
    {
      "id": "1234567",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "permalink": "https://www.threads.net/@threadsapitestuser/post/abcdefg",
      "username": "threadsapitestuser",
      "text": "Reply Text",
      "timestamp": "2023-10-17T05:42:03+0000",
      "shortcode": "abcdefg",
      "is_quote_post": false,
      "has_replies": false,
      "root_post": {
        "id": "1234567890"
      },
      "replied_to": {
        "id": "1234567890"
      },
      "is_reply": true,
      "is_reply_owned_by_me": true,
      "reply_audience": "EVERYONE"
    },
  ],
  "paging": {
    "cursors": {
      "before": "BEFORE_CURSOR",
      "after": "AFTER_CURSOR"
    }
  }
}

Hide Replies

Use the /manage_reply endpoint to hide/unhide any top-level replies. This will automatically hide/unhide all the nested replies. Note: Replies nested deeper than the top-level reply cannot be targeted in isolation to be hidden/unhidden.

Example Request

curl -X POST \
  -F "hide={true | false}" \
  -F "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_REPLY_ID>/manage_reply"

Example Response

{
 "success": true
}

Respond to Replies

Use the reply_to_id parameter to reply to a specific reply under the root post. The caller should be the owner of the root post.

Example Request

curl -X POST \
  -F "media_type=<MEDIA_TYPE>" \
  -F "text=<TEXT>" \
  -F "reply_to_id=<THREADS_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/me/threads"

Example Response

{
 "id": "1234567890"
}

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

  • creation_id — Identifier of the Threads media container created from the /threads endpoint.

Example Request

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

Example Response

{
  "id": "1234567" // Threads Reply Media ID
}

Control Who Can Reply

Use the reply_control parameter to specify who can reply to a post being created for publishing. This parameter accepts one of the 3 options: everyone, accounts_you_follow, and mentioned_only.

Example Request

curl -X POST \
  -F "media_type=<MEDIA_TYPE>" \
  -F "text=<TEXT>" \
  -F "reply_control=accounts_you_follow" \
  -F "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/me/threads"

Example Response

{
 "id": "1234567890"
}

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

  • creation_id — Identifier of the Threads media container created from the /threads endpoint.

Example Request

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

Example Response

{
  "id": "1234567" // Threads Media ID
}