> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 依 Social ID 取得貼文分析

> 使用 Social Post ID 取得貼文的即時分析

export const XByoNotice = () => <Info>
  <strong>Targeting X/Twitter?</strong> Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:
  <br /><br />
  <code>X-Twitter-OAuth1-Api-Key</code> — Your API Key (Consumer Key)<br />
  <code>X-Twitter-OAuth1-Api-Secret</code> — Your API Key Secret (Consumer Secret)
  <br /><br />
  <strong>One-time setup per Ayrshare account.</strong> You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do <em>not</em> create a new app per customer.
  <br /><br />
  Not linked yet? See the <a href="/dashboard/connect-social-accounts/x-twitter-byo-keys">full setup guide</a> to connect your X account.
  <br /><br />
  Your keys are never logged or stored by Ayrshare.
</Info>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["business"]} maxPackRequired={false} />

<XByoNotice />

提供底層的 [Social Post ID](/apis/overview#social-post-id)，即可取得非透過 Ayrshare 發送之貼文的分析。
此 ID 會回傳在 [/post 端點](/apis/post/post)的 `postIds` 欄位中。

要取得分析資料，已連結的帳號必須是該貼文的擁有者（例外：YouTube；請見下方說明）。支援的平台：`Facebook`、`Instagram`、`LinkedIn`、`Threads`、`TikTok`、`Twitter` 與 `YouTube`。

<ul className="custom-bullets">
  <li>
    呼叫方式與[貼文分析端點](/apis/analytics/post)相同。主要差異在於使用社群網路回傳的 post id，而不是 Ayrshare ID。同時需加上 `searchPlatformId: true` 參數，告知端點你是以 Social Post ID 進行查詢。
  </li>

  <li>
    使用[取得全部貼文歷史端點](/apis/history/overview)，可取回非透過 Ayrshare 發送的貼文，這些貼文的 ID 位於 `id` 欄位。
  </li>

  <li>
    建議僅對非透過 Ayrshare 發送的貼文使用此端點。對於透過 Ayrshare 發送的貼文，請使用[分析端點](/apis/analytics/post)。
  </li>

  <li>
    在使用者帳號由個人帳號轉為商業帳號之前所發布的 Instagram 貼文，其分析資料有限。
  </li>

  <li>
    若你透過 social id 方法取得不屬於自己頻道的 YouTube 貼文分析，API 會回傳關於該內容的描述性中繼資料，但所有數值指標都會顯示為零。描述性資訊（例如標題、描述、標籤、頻道名稱、隱私狀態、縮圖 URL）會正確填入，提供影片內容的上下文；然而所有數值型表現指標，包括觀看、按讚、留言、分享、訂閱者變化、觀看時間與播放清單新增，都會回傳為零。
  </li>

  <li>
    當你對 X/Twitter Thread 使用 `postIds` 時，Thread 中每則 Tweet 的 Social Post ID 都必須個別提供；查詢父貼文並不會自動包含 Thread 中的其他 Tweet。
  </li>
</ul>

## 標頭參數

<HeaderAPI />

## 主體參數

<Note>
  必須提供 `id` 或 `postIds` 其一。對單一貼文使用 `id`；若要在單一請求中取得多則貼文的分析，請使用 `postIds`。
</Note>

<ParamField body="id" type="string">
  由 [/post 端點](/apis/post/post)回傳的 [Social Post ID](/apis/overview#social-post-id)。這是 `postIds` 陣列中個別社群網路的 `id` 欄位。`id` 與 `postIds` 至少必須提供其一。
</ParamField>

<ParamField body="postIds" type="array">
  [Social Post ID](/apis/overview#social-post-id) 陣列，可在單一請求中取得多則貼文的分析。最多允許 100 個 ID。`id` 與 `postIds` 至少必須提供其一。

  ```json theme={"system"}
  {
    "postIds": ["1979851549871354062", "2011793803951137234"]
  }
  ```
</ParamField>

<ParamField body="platforms" type="array" required>
  要取得分析的平台字串陣列。僅允許一個值。

  可用值：

  ```json theme={"system"}
  {
    "platforms": ["facebook", "instagram", "linkedin", "threads",
                  "tiktok", "twitter", "youtube"]
  }
  ```
</ParamField>

<ParamField body="searchPlatformId" type="boolean" default={false} required>
  設為 `true` 以依 Social Post ID 進行查詢。
</ParamField>

<RequestExample>
  ```json Single Post theme={"system"}
  {
      // Facebook Social Post ID
      "id": "104923907983682_108329000309742",
      "platforms": [
        // Select only one platform at a time:
        // facebook, instagram, youtube, threads, tiktok, or twitter
          "facebook"
      ],
      "searchPlatformId": true // Required
  }
  ```

  ```json Multiple Posts theme={"system"}
  {
      // Array of Social Post IDs (max 100)
      "postIds": ["1979851549871354062", "2011793803951137234"],
      "platforms": [
        // Select only one platform at a time:
        // facebook, instagram, youtube, threads, tiktok, or twitter
          "twitter"
      ],
      "searchPlatformId": true // Required
  }
  ```
</RequestExample>

<Info>
  當累積指標（例如按讚、留言、觀看數）暫時無法從社群網路取得時，API 會自動以已儲存的資料回填。每個平台的 `analytics` 物件可能會出現兩個選填欄位：

  * **`backfilledFrom`**（string，ISO 8601）— 當有一個以上的累積指標是以儲存資料替代時出現。時間戳表示儲存資料的最後更新時間。
  * **`recoveredFrom`**（string，ISO 8601）— 當整個分析回應因為 API 完全失敗而從儲存資料還原時出現。時間戳表示儲存資料的最後更新時間。

  超過 4 天的儲存資料會視為過期，不會用於回填或還原。
</Info>

<ResponseExample>
  ```json 200: Single Post Response theme={"system"}
  {
    /**
      The response is the same as Analytics on a Post.
      Please see that endpoint for details.

      Note: Some metrics are not available for posts not owned by the authorized account.
      For example: X does not return non-public metrics or organic metrics for Tweets not sent by the authorized user.
    */
  }
  ```

  ```json 200: Multiple Posts Response theme={"system"}
  {
      "twitter": [
          {
              "id": "1313589441919827982",    // Twitter Social Post ID
              "postUrl": "https://www.twitter.com/myaccount/1313589441919827982",
              "analytics": {
                  "created": "2022-09-07T22:12:10.000Z",
                  "entities": {
                      "urls": [
                          {
                              "start": 77,
                              "end": 96,
                              "url": "https://t.co/abc123",
                              "expandedUrl": "https://www.ayrshare.com/docs",
                              "displayUrl": "ayrshare.com/docs",
                              "unwoundUrl": "https://www.ayrshare.com/docs"
                          }
                      ],
                      "hashtags": [
                          {
                              "start": 97,
                              "end": 112,
                              "tag": "SocialMediaAPI"
                          }
                      ],
                      "mentions": [
                          {
                              "start": 113,
                              "end": 122,
                              "username": "ayrshare"
                          }
                      ]
                  },
                  "name": "Wonder World",
                  "post": "Just launched our social media campaign using Ayrshare! Check out the API at https://t.co/abc123 #SocialMediaAPI @ayrshare",
                  "publicMetrics": {
                      "retweetCount": 0,
                      "quoteCount": 0,
                      "likeCount": 0,
                      "replyCount": 0,
                      "bookmarkCount": 0,
                      "impressionCount": 23
                  },
                  "nonPublicMetrics": {
                      "userProfileClicks": 1,
                      "engagements": 1,
                      "impressionCount": 5
                  },
                  "organicMetrics": {
                      "likeCount": 0,
                      "impressionCount": 5,
                      "replyCount": 0,
                      "retweetCount": 0,
                      "userProfileClicks": 1
                  },
                  "username": "wondrous"
              },
              "lastUpdated": "2022-04-23T18:44:29.778Z",
              "nextUpdate": "2022-04-23T19:19:29.778Z"
          },
          {
              "id": "1313589441919827999",    // Twitter Social Post ID
              "postUrl": "https://www.twitter.com/myaccount/1313589441919827999",
              "analytics": {
                  "created": "2022-09-08T14:30:00.000Z",
                  "name": "Wonder World",
                  "post": "Another great day for social media automation!",
                  "publicMetrics": {
                      "retweetCount": 5,
                      "quoteCount": 2,
                      "likeCount": 15,
                      "replyCount": 3,
                      "bookmarkCount": 1,
                      "impressionCount": 150
                  },
                  "nonPublicMetrics": {
                      "userProfileClicks": 8,
                      "engagements": 12,
                      "impressionCount": 145
                  },
                  "organicMetrics": {
                      "likeCount": 15,
                      "impressionCount": 145,
                      "replyCount": 3,
                      "retweetCount": 5,
                      "userProfileClicks": 8
                  },
                  "username": "wondrous"
              },
              "lastUpdated": "2022-04-23T18:44:29.778Z",
              "nextUpdate": "2022-04-23T19:19:29.778Z"
          }
      ],
      "status": "success",
      "code": 200
  }
  ```

  ```json 200: Backfilled Response theme={"system"}
  {
      "twitter": [
          {
              "id": "1313589441919827982",
              "postUrl": "https://www.twitter.com/myaccount/1313589441919827982",
              "analytics": {
                  "created": "2022-09-07T22:12:10.000Z",
                  "name": "Wonder World",
                  "post": "Just launched our social media campaign!",
                  "publicMetrics": {
                      "retweetCount": 5,
                      "quoteCount": 2,
                      "likeCount": 15,
                      "replyCount": 3,
                      "bookmarkCount": 1,
                      "impressionCount": 150
                  },
                  "username": "wondrous",
                  "backfilledFrom": "2026-04-08T14:30:00.000Z"
              },
              "lastUpdated": "2026-04-09T10:15:00.000Z",
              "nextUpdate": "2026-04-09T10:26:00.000Z"
          }
      ],
      "status": "success",
      "code": 200
  }
  ```

  ```json 200: Recovered Response theme={"system"}
  {
      "twitter": [
          {
              "id": "1313589441919827982",
              "postUrl": "https://www.twitter.com/myaccount/1313589441919827982",
              "analytics": {
                  "created": "2022-09-07T22:12:10.000Z",
                  "name": "Wonder World",
                  "post": "Just launched our social media campaign!",
                  "publicMetrics": {
                      "retweetCount": 5,
                      "quoteCount": 2,
                      "likeCount": 15,
                      "replyCount": 3,
                      "bookmarkCount": 1,
                      "impressionCount": 150
                  },
                  "username": "wondrous",
                  "recoveredFrom": "2026-04-08T14:30:00.000Z"
              },
              "lastUpdated": "2026-04-09T10:15:00.000Z",
              "nextUpdate": "2026-04-09T10:26:00.000Z"
          }
      ],
      "status": "success",
      "code": 200
  }
  ```

  ```json 400: Bad Request theme={"system"}
  {
      "lastUpdated": "2023-12-08T03:40:31.185Z",
      "nextUpdate": "2023-12-08T03:51:31.185Z",
      "youtube": {
          "action": "post",
          "status": "error",
          "code": 186,
          "message": "Post ID not found. Please verify the top level ID returned from the /post endpoint is being sent, the Profile Key is included if applicable, and the post at the social network has not been deleted. If you are trying to retrieve a post originating outside of Ayrshare, please use the /rest-api/endpoints/analytics#analytics-by-social-id",
          "id": "dtuu-jDp4381"
      }
  }
  ```
</ResponseExample>