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

# تحليلات على منشور حسب معرف اجتماعي

> احصل على تحليلات فورية للمنشورات باستخدام معرف المنشور الاجتماعي

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 />

استرجع تحليلات المنشورات التي لم تنشأ عبر Ayrshare عن طريق توفير [معرف المنشور الاجتماعي](/apis/overview#social-post-id) منخفض المستوى.
يتم إرجاع هذا المعرف في حقل `postIds` من [نقطة نهاية /post](/apis/post/post).

يجب أن يكون الحساب المرتبط هو مالك المنشور لاسترجاع التحليلات (استثناء: YouTube؛ راجع أدناه). المنصات المدعومة: `Facebook` و`Instagram` و`LinkedIn` و`Threads` و`TikTok` و`Twitter` و`YouTube`.

<ul className="custom-bullets">
  <li>
    الاستدعاء هو نفسه [نقطة نهاية التحليلات على منشور](/apis/analytics/post). الفرق
    الرئيسي هو أنك تستخدم معرف المنشور الذي تُرجعه الشبكة الاجتماعية بدلاً من معرف Ayrshare. تضمّن
    أيضًا المعلمة `searchPlatformId: true` لإعلام نقطة النهاية بأنك تبحث بواسطة
    معرف المنشور الاجتماعي.
  </li>

  <li>
    استخدم [نقطة نهاية الحصول على كل سجل المنشورات](/apis/history/overview) لاسترجاع المنشورات والمعرفات
    التي نشأت خارج Ayrshare والموجودة في حقل `id`.
  </li>

  <li>
    يُنصح باستخدامها فقط للمنشورات التي لم تُرسل عبر Ayrshare. بالنسبة للمنشورات المُرسلة عبر Ayrshare، استخدم
    [نقطة نهاية التحليلات](/apis/analytics/post).
  </li>

  <li>
    التحليلات على منشورات Instagram التي نُشرت قبل تحويل حساب المستخدم إلى
    حساب أعمال من حساب شخصي لها تحليلات محدودة.
  </li>

  <li>
    عند استرجاع تحليلات YouTube لمنشور لا ينتمي إلى قناتك باستخدام طريقة المعرف
    الاجتماعي، ستُرجع واجهة برمجة التطبيقات بيانات وصفية عن المحتوى بينما تعرض أصفارًا لجميع
    المقاييس الرقمية. سيتم تعبئة المعلومات الوصفية مثل العنوان والوصف والوسوم وعنوان القناة
    وحالة الخصوصية وعناوين URL للصور المصغرة بشكل صحيح، مما يوفر سياقًا حول
    محتوى الفيديو. ومع ذلك، فإن جميع مقاييس الأداء الرقمية بما في ذلك المشاهدات والإعجابات والتعليقات
    والمشاركات وتغيرات المشتركين ومدة المشاهدة وإضافات قائمة التشغيل ستُرجع كقيم صفرية.
  </li>

  <li>
    عند استخدام `postIds` لسلاسل X/Twitter، يجب توفير معرف المنشور الاجتماعي لكل تغريدة
    بشكل فردي؛ لا يتم تضمين تغريدات السلسلة تلقائيًا عند الاستعلام عن المنشور الأصلي.
  </li>
</ul>

## معلمات الترويسة

<HeaderAPI />

## معلمات النص

<Note>
  يجب توفير إما `id` أو `postIds`. استخدم `id` لمنشور واحد أو `postIds` لاسترجاع تحليلات لعدة منشورات في طلب واحد.
</Note>

<ParamField body="id" type="string">
  [معرف المنشور الاجتماعي](/apis/overview#social-post-id) الذي يتم إرجاعه من [نقطة نهاية
  /post](/apis/post/post). هذا هو حقل `id` لشبكة اجتماعية فردية موجودة في
  مصفوفة `postIds`. إما `id` أو `postIds` مطلوب.
</ParamField>

<ParamField body="postIds" type="array">
  مصفوفة من [معرفات المنشور الاجتماعي](/apis/overview#social-post-id) لاسترجاع التحليلات لعدة منشورات في طلب واحد. يُسمح بحد أقصى 100 معرف. إما `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` للبحث بواسطة معرف المنشور الاجتماعي.
</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>
  عندما تكون المقاييس التراكمية (مثل الإعجابات والتعليقات والمشاهدات) غير متوفرة مؤقتًا من الشبكة الاجتماعية، تقوم واجهة برمجة التطبيقات تلقائيًا بتعبئتها من البيانات المخزنة. قد يظهر حقلان اختياريان في كائن `analytics` لكل منصة:

  * **`backfilledFrom`** (سلسلة، ISO 8601) — موجود عندما تم استبدال مقياس تراكمي واحد أو أكثر من البيانات المخزنة. يشير الطابع الزمني إلى آخر تحديث للبيانات المخزنة.
  * **`recoveredFrom`** (سلسلة، ISO 8601) — موجود عندما تم استرداد استجابة التحليلات بأكملها من البيانات المخزنة بسبب فشل كامل في واجهة برمجة التطبيقات. يشير الطابع الزمني إلى آخر تحديث للبيانات المخزنة.

  تُعتبر البيانات المخزنة الأقدم من 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>