Retrieve Threads Media Objects

This document shows you how to retrieve:

A List of All Threads Created by a User
A Single Threads Media Object

Retrieve a List of All a User's Threads

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

Permissions

The Threads Retrieval 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.

Limitations

You may only fetch a paginated list of all threads created by the app-scoped user.

Fields

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

Name	Description
`id` (default)	The media's ID.
`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 post will be one of these values: `TEXT_POST`, `IMAGE`, `VIDEO`, `CAROUSEL_ALBUM`, `AUDIO`, or `REPOST_FACADE`.
`media_url`	The post’s media URL.
`permalink`	Permanent link to the post. Will be omitted if the media contains copyrighted material or has been flagged for a copyright violation.
`owner`	Threads user ID who created the post. Note: This is only available on top-level posts that you own.
`username`	Threads username who created the post.
`text`	Represents text for a Threads post.
`timestamp`	Post time. The publish date in ISO 8601 format.
`shortcode`	Shortcode of the media.
`thumbnail_url`	URL of thumbnail. This only shows up for Threads media with video.
`children`	List of child posts. This only shows up for carousel posts.
`is_quote_post`	Indicates if the media is a quoted post made by another user.
`quoted_post`	Media ID of the post that was quoted. Note: This only appears on quote posts.
`reposted_post`	Media ID of the post that was reposted. Note: This only appears on reposts.
`alt_text`	The accessibility text label or description for an image or video in a Threads post.
`link_attachment_url`	The URL attached to a Threads post.
`gif_url`	The URL of the GIF attached to the post (if any). Note: This will only show up on posts that have a GIF attachment.

Example Request

curl -s -X GET \
"https://graph.threads.net/v1.0/me/threads?fields=id,media_product_type,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post&since=2023-10-15&until=2023-11-18&limit=1&access_token=$THREADS_ACCESS_TOKEN"

Example Response

{
  "data": [
    {
      "id": "1234567",
      "media_product_type": "THREADS",
      "media_type": "TEXT_POST",
      "permalink": "https://www.threads.net/@threadsapitestuser/post/abcdefg",
      "owner": {
        "id": "1234567"
      },
      "username": "threadsapitestuser",
      "text": "Today Is Monday",
      "timestamp": "2023-10-17T05:42:03+0000",
      "shortcode": "abcdefg",
      "is_quote_post": false
    },
  ],
  "paging": {
    "cursors": {
      "before": "BEFORE_CURSOR",
      "after": "AFTER_CURSOR"
    }
  }
}

Retrieve a Single Threads Media Object

You can also use the GET /{threads-media-id} endpoint to return an individual Threads media object.

Permissions

threads_basic — Required for making any calls to all Threads API endpoints.

If your app has not been approved for advanced access for the threads_basic permission, only posts created by a Threads tester are retrievable. After approval, public posts created by other users will be retrievable.

Example Request

curl -s -X GET \
"https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>?fields=id,media_product_type,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post&access_token=<THREADS_ACCESS_TOKEN>"

Example Response

{
  "id": "1234567",
  "media_product_type": "THREADS",
  "media_type": "TEXT_POST",
  "permalink": "https://www.threads.net/@threadsapitestuser/post/abcdefg",
  "owner": {
    "id": "1234567"
  },
  "username": "threadsapitestuser",
  "text": "Hello World",
  "timestamp": "2023-10-09T23:18:27+0000",
  "shortcode": "abcdefg",
  "is_quote_post": false
}