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

# Analytics on a Post by Social ID

> Get real-time analytics for posts using the 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 />
  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 === "basic") {
      displayPlans = ["Basic", "Premium", "Business", "Enterprise"];
    } else if (lowerCasePlan === "business") {
      displayPlans = ["Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "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 />

Retrieve analytics for posts that did not originate via Ayrshare by providing the low-level [Social Post ID](/apis/overview#social-post-id).
This ID is returned in the `postIds` field of the [/post endpoint](/apis/post/post).

The linked account must be the owner of the post to retrieve the analytics (exception: YouTube; see below). Support platforms: `Facebook`, `Instagram`, `LinkedIn`, `Threads`, `TikTok`, `Twitter`, and `YouTube`.

<ul className="custom-bullets">
  <li>
    The call is the same as the [Analytics on a Post endpoint](/apis/analytics/post). The key
    difference is you use the post id return by the social network instead of the Ayrshare ID. Also
    include the `searchPlatformId: true` parameter to notify the endpoint you're searching by the
    Social Post ID.
  </li>

  <li>
    Use the [Get All Post History endpoint](/apis/history/overview) to retrieve posts and IDs
    originating outside of Ayrshare found in the `id` field.
  </li>

  <li>
    Recommend to only use for posts not sent via Ayrshare. For posts sent via Ayrshare, use the
    [analytics endpoint](/apis/analytics/post).
  </li>

  <li>
    Analytics on Instagram posts that were published before the user's account was converted to a
    business account from a personal account have limited analytics.
  </li>

  <li>
    If retrieving YouTube analytics for a post that doesn't belong to your channel using the social
    ID method, the API will return descriptive metadata about the content while showing zeros for
    all numerical metrics. Descriptive information such as title, description, tags, channel title,
    privacy status, and thumbnail URLs will be correctly populated, providing context about the
    video content. However, all numerical performance metrics including views, likes, comments,
    shares, subscriber changes, watch time, and playlist additions will return as zero values.
  </li>

  <li>
    When using `postIds` for X/Twitter threads, each tweet's Social Post ID must be provided
    individually, thread tweets are not automatically included when querying the parent post.
  </li>
</ul>

## Header Parameters

<HeaderAPI />

## Body Parameters

<Note>
  Either `id` or `postIds` must be provided. Use `id` for a single post or `postIds` for retrieving analytics on multiple posts in a single request.
</Note>

<ParamField body="id" type="string">
  [Social Post ID](/apis/overview#social-post-id) returned from the [/post
  endpoint](/apis/post/post). This is the `id` field for an individual social network found in the
  `postIds` array. Either `id` or `postIds` is required.
</ParamField>

<ParamField body="postIds" type="array">
  Array of [Social Post IDs](/apis/overview#social-post-id) to retrieve analytics for multiple posts in a single request. Maximum of 100 IDs allowed. Either `id` or `postIds` is required.

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

<ParamField body="platforms" type="array" required>
  String array of platforms to retrieve analytics. Only one value is allowed.

  Available values:

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

<ParamField body="searchPlatformId" type="boolean" default={false} required>
  Set to `true` to search by the 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>
  When cumulative metrics (e.g., likes, comments, views) are temporarily unavailable from the social network, the API automatically backfills them from stored data. Two optional fields may appear in the per-platform `analytics` object:

  * **`backfilledFrom`** (string, ISO 8601) — Present when one or more cumulative metrics were substituted from stored data. The timestamp indicates when the stored data was last updated.
  * **`recoveredFrom`** (string, ISO 8601) — Present when the entire analytics response was recovered from stored data due to a complete API failure. The timestamp indicates when the stored data was last updated.

  Stored data older than 4 days is considered stale and will not be used for backfill or recovery.
</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>