Threads API

Threads 洞察報告 API

Threads 洞察報告 API 可讓您讀取用戶自己的 Threads 洞察報告。

權限

Threads 洞察報告 API 需要根據您的目標節點，取得適當的存取權杖和權限。進行測試時，您可以使用圖形 API 測試工具，輕鬆產生權杖並授予應用程式權限。

  • threads_basic — 對所有 Threads API 端點進行任何呼叫時的必要項目。
  • threads_manage_insights — 對洞察報告端點進行 GET 呼叫時的必要項目。

限制

  • 用戶洞察報告 since 和 until 參數不適用於 2024 年 4 月 13 日（Unix 時間戳記 1712991600）之前的日期。

影音內容洞察報告

若要擷取可用的洞察報告衡量指標，請傳送 GET 要求至 /{threads-media-id}/insights 端點，其中 metric 參數應包含所要傳回的衡量指標清單（以逗號分隔）。

注意：

  • 傳回的衡量指標不會擷取巢狀回覆的衡量指標。
  • 針對 REPOST_FACADE 貼文，會傳回空陣列，因為這些貼文是由其他用戶發佈的貼文。

可用的衡量指標

名稱說明

views

您的貼文被播放或顯示的次數。

注意：此衡量指標仍在調整中。

likes

貼文獲得的讃數。

replies

貼文獲得的回覆次數。

注意：如果所要求的影音內容是根貼文，則此數目包含回覆總數。如果影音內容本身是回覆，則此數目只包含直接回覆。

reposts

貼文獲得轉發的次數。

quotes

貼文獲得引用的次數。

shares

Threads 貼文被分享的次數。

注意：此衡量指標仍在調整中。

要求範例

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

回應範例

{
  "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"
    }
  ]
}

用戶洞察報告

若要擷取可用的用戶洞察報告衡量指標，請傳送 GET 要求至 /{threads-user-id}/threads_insights 端點，其中包含 metric 參數，以及選用性的 since 和 until 參數。

不保證用戶洞察報告在 2024 年 6 月 1 日之前有效。

參數

名稱說明

since

選用項目。
與 until 參數一起用來定義範圍。如果省略 since 和 until，則預設為 2 天的範圍：昨天到今天。
注意：可以使用的最早 Unix 時間戳記是 1712991600，早於此時間的任何時間戳記都會被拒絕。

格式：Unix 時間戳記

until

選用項目。
與 since 參數一起用來定義範圍。如果省略 since 和 until，則預設為 2 天的範圍：昨天到今天。
注意：可以使用的最早 Unix 時間戳記是 1712991600，早於此時間的任何時間戳記都會被拒絕。

格式：Unix 時間戳記

metric

必要項目。
所要傳回的衡量指標清單（以逗號分隔）。必須包含至少其中一個用戶衡量指標值。

用戶衡量指標

名稱回應類型說明

views

時間序列

個人檔案獲得瀏覽的次數。

likes

總數值

貼文獲得的讚數。

replies

總數值

貼文獲得的回覆次數。

注意：此數目僅包含最上層回覆。

reposts

總數值

貼文獲得轉發的次數。

quotes

總數值

貼文獲得引用的次數。

clicks

連結總數值

用戶點擊您分享網址的次數。

followers_count

總數值

您在 Threads 上的追蹤者總數。

注意：

  • 此衡量指標不支援 since 和 until 參數。
  • 此衡量指標不適用於未連結 Instagram 帳號的 Threads 個人檔案。

follower_demographics

總數值

追蹤者的人口統計資料特性，包括國家／地區、縣市和性別分佈。

注意：

  • 此衡量指標不支援 since 和 until 參數。
  • Threads 個人檔案至少須有 100 個追蹤者，才能擷取此衡量指標。
  • 此衡量指標不適用於未連結 Instagram 帳號的 Threads 個人檔案。
  • breakdown 參數只能有一個，且此參數必須等於 country、city、age 或 gender 其中一個值。

要求範例

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

時間序列衡量指標回應範例

{
  "data": [
    {
      "name": "views",
      "period": "day",
      "values": [
        {
          "value": 10,
          "end_time": "2024-07-12T08:00:00+0000"
        },
        {
          "value": 20,
          "end_time": "2024-07-15T08:00:00+0000"
        },
        {
          "value": 30,
          "end_time": "2024-07-16T08:00:00+0000"
        }
      ],
      "title": "views",
      "description": "The number of times your profile was viewed.",
      "id": "37602215421583/insights/views/day"
    }
  ]
}

總數值衡量指標回應範例

{
  "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"
    }
  ]
}

連結總數值回應範例

{
  "data": [
    {
      "name": "clicks",
      "period": "day",
      "link_total_values": [
        {
          "value": 11,
          "link_url": "https://ai.meta.com/blog/"
        }
      ],
      "title": "clicks",
      "description": "The number of times users clicked on a link.",
      "id": "37602215421583/insights/clicks/day"
    }
  ]
}

錯誤代碼

錯誤說明

ErrorCode::THREADS_API__FEATURE_NOT_AVAILABLE

此用戶無權存取此 Threads API 功能。

適用於未連結 Instagram 帳號但嘗試存取 followers_count 或 follower_demographics 衡量指標的 Threads 個人檔案。