> ## 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.

# 按社交 ID 查询帖子分析

> 使用社交帖子 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 />

通过提供底层的[社交帖子 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)相同。关键区别在于你使用的是社交网络返回的帖子 ID，而不是 Ayrshare 的 ID。同时需要包含 `searchPlatformId: true` 参数，以通知端点你正在按社交帖子 ID 进行查询。
  </li>

  <li>
    使用[获取全部帖子历史端点](/apis/history/overview)可以获取在 Ayrshare 外部发布的帖子及其在 `id` 字段中返回的 ID。
  </li>

  <li>
    建议仅对未通过 Ayrshare 发送的帖子使用。对于通过 Ayrshare 发送的帖子，请使用[分析端点](/apis/analytics/post)。
  </li>

  <li>
    对于在用户账户由个人账户切换为商业账户之前发布的 Instagram 帖子，其分析数据有限。
  </li>

  <li>
    如果使用社交 ID 方法获取不属于你频道的 YouTube 帖子的分析数据，API 会返回该内容的描述性元数据，同时所有数值指标显示为零。诸如标题、描述、标签、频道标题、隐私状态和缩略图 URL 等描述性信息会被正确填充，为视频内容提供背景。然而，所有数值型表现指标——包括观看数、点赞数、评论数、分享数、订阅者变化、观看时长和加入播放列表次数——都会返回为零。
  </li>

  <li>
    在为 X/Twitter Threads 使用 `postIds` 时，必须单独提供每条推文的社交帖子 ID，查询父帖子时不会自动包含线程中的推文。
  </li>
</ul>

## 请求头参数

<HeaderAPI />

## 请求体参数

<Note>
  必须提供 `id` 或 `postIds` 之一。对于单个帖子使用 `id`；如果要在一次请求中获取多个帖子的分析数据，请使用 `postIds`。
</Note>

<ParamField body="id" type="string">
  从 [/post 端点](/apis/post/post) 返回的[社交帖子 ID](/apis/overview#social-post-id)。这是 `postIds` 数组中每个社交网络单独的 `id` 字段。`id` 或 `postIds` 必填其一。
</ParamField>

<ParamField body="postIds" type="array">
  用于在一次请求中获取多个帖子分析数据的[社交帖子 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` 时按社交帖子 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`**（字符串，ISO 8601）— 当有一个或多个累计指标被存储数据替换时出现。该时间戳表示存储数据最后更新的时间。
  * **`recoveredFrom`**（字符串，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>