Threads Insights API

The Threads Insights API allows you to read the insights from users' own Threads.

Permissions

The Threads Insights 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_insights — Required for making GET calls to insights endpoints.

Limitations

The user insights since and until parameters do not work for dates before April 13, 2024 (Unix timestamp 1712991600 ).

Media Insights

To retrieve the available insights metrics, send a GET request to the /{threads-media-id}/insights endpoint with the metric parameter containing a comma-separated list of metrics to be returned.

Note:

Returned metrics do not capture nested replies' metrics.
Metrics will not be returned for REPOST_FACADE posts because it is a post made by another user.

Available Metrics

Name	Description
`views`	The number of times the post was viewed. Note:This metric is in development .
`likes`	The number of likes on the post.
`replies`	The number of replies on the post. Note:This number includes only top-level replies.
`reposts`	The number of times the post was reposted.
`quotes`	The number of times the post was quoted.

Example Request

curl -s -X GET \
  -F "metric=likes,replies" \
	-F "access_token=<THREADS_ACCESS_TOKEN>"
"https://graph.threads.net/v1.0/<THREADS_MEDIA_ID>/insights"

Example Response

{
  "data": [
    {
      "name": "likes",
      "period": "lifetime",
      "values": [
        {
          "value": 100
        }
      ],
      "title": "Likes",
      "description": "The number of likes on your post.",
      "id": "<media_id>/insights/likes/lifetime"
    },
    {
      "name": "replies",
      "period": "lifetime",
      "values": [
        {
          "value": 10
        }
      ],
      "title": "Replies",
      "description": "The number of replies on your post.",
      "id": "<media_id>/insights/replies/lifetime"
    }
  ]
}

User Insights

To retrieve the available user insights metrics, send a GET request to the /{threads-user-id}/threads_insights endpoint with the metric parameter, and optionally, the since and until parameters.

Parameters

Name Description

Name	Description
`since`	Optional. Used in conjunction with the `until` parameter to define a range. If you omit `since` and `until` , it defaults to a 2-day range: yesterday through today. Note:The earliest Unix timestamp that can be used is `1712991600` , any timestamp before that will be rejected. Format:Unix Timestamp
`until`	Optional. Used in conjunction with the `since` parameter to define a range. If you omit `since` and `until` , it defaults to a 2-day range: yesterday through today. Note:The earliest Unix timestamp that can be used is `1712991600` , any timestamp before that will be rejected. Format:Unix Timestamp
`metric`	Required.A comma-separated list of the metrics to be returned. Must be at least one of the account metrics values.

since

Optional.
Used in conjunction with the until parameter to define a range. If you omit since and until , it defaults to a 2-day range: yesterday through today.
Note:The earliest Unix timestamp that can be used is 1712991600 , any timestamp before that will be rejected.

Format:Unix Timestamp

until

Optional.
Used in conjunction with the since parameter to define a range. If you omit since and until , it defaults to a 2-day range: yesterday through today.
Note:The earliest Unix timestamp that can be used is 1712991600 , any timestamp before that will be rejected.

Format:Unix Timestamp

metric

Required.A comma-separated list of the metrics to be returned. Must be at least one of the account metrics values.

Account Metrics

Name

Response Type

Description

views

Time Series

The number of times your profile was viewed.

likes

Total Value

The number of likes on your posts.

replies

Total Value

The number of replies on your posts.

Note:This number includes only top-level replies.

reposts

Total Value

The number of times your posts were reposted.

quotes

Total Value

The number of times your posts were quoted.

followers_count

Total Value

Your total number of followers on Threads.

Note:

This metric does not support the since and until parameters.

follower_demographics

Total Value

The demographic characteristics of followers, including countries, cities, and gender distribution.

Note:

This metric does not support the since and until parameters.
A Threads account must have at least 100 followers to fetch this metric.
Mustcontain a breakdown parameter equal to one of the following values: country , city , age , or gender .

Example Request

curl -s -X GET \
  -F "metric=views" \
  -F "access_token=<ACCESS_TOKEN>" \
"https://graph.threads.net/v1.0/<THREADS_USER_ID>/threads_insights"

Example Time Series Metric Response

{
  "data": [
    {
      "name": "views",
      "period": "day",
      "values": [
        {
          "value": 10,
          "end_time": "1713789497"
        },
        {
          "value": 20,
          "end_time": "1713789497"
        },
        {
          "value": 30,
          "end_time": "1713789497"
        }
      ],
      "title": "views",
      "description": "The number of times your profile was viewed.",
      "id": "37602215421583/insights/views/day"
    }
  ]
}

Example Total Value Metric Response

{
  "data": [
    {
      "name": "views",
      "period": "day",
      "total_value" : {
        “value”: 1
      }
      "title": "views",
      "description": "The number of times your profile was viewed.",
      "id": "37602215421583/insights/views/day"
    }
  ]
}