Skip to main content
POST
Targeting X/Twitter? Starting March 31, 2026, all X operations require your own API credentials. After linking X via OAuth, include these 2 headers in your request:

X-Twitter-OAuth1-Api-Key — Your API Key (Consumer Key)
X-Twitter-OAuth1-Api-Secret — Your API Key Secret (Consumer Secret)

One-time setup per Ayrshare account. You create one X Developer App and reuse the same API Key and Secret across every sub-profile / end-user you link. You do not create a new app per customer.

Not linked yet? See the full setup guide to connect your X account.

Your keys are never logged or stored by Ayrshare.
Get real-time analytics such as likes, impressions, views, and reactions for a post that was sent via Ayrshare using the Ayrshare Post ID. For analytics on posts originating outside of Ayrshare, see Analytics by Social Post ID.
Facebook: some reach and video metrics were retired by Meta (June 15, 2026). Meta removed the unique-impression and 3-second video-view Insights metrics across all Graph API versions, so the Facebook analytics object no longer returns impressionsUnique, impressionsFanUnique, impressionsOrganicUnique, impressionsPaidUnique, or videoViewsUnique. For reach, use totalMediaViewUnique (the number of unique people this post was played or displayed to), Meta’s Total Unique Media Views replacement for the retired unique-impression fields. mediaView remains available for total, non-unique views. Other commonly used fields such as reactionsByType and videoViews are unaffected. Reference: Upcoming API Changes — June 15, 2026.

Additional Information

  • The following platforms are currently supported: Bluesky, Facebook Pages, Instagram, X/Twitter, LinkedIn, Pinterest, Reddit, Snapchat, Threads, TikTok, and YouTube.
  • Facebook and Instagram comment counts shown in the API may differ from counts displayed in the social apps. This occurs for two reasons: - Some users have privacy settings that hide their comments from non-friends or users without mutual connections. These private comments are still included in the total comment count. - There may be inconsistencies in the data reported by Meta.
  • Instagram igReelsAggregatedAllPlaysCount and playsCount shown in the API may differ from the counts displayed in the social apps. This can occur for a couple of reasons:
    • The post was promoted. Only organic plays are included in the API response.
    • There may be inconsistencies in the data reported by Meta.
  • X/Twitter Threads return as an Array of objects, with each object corresponding to a Tweet in the Thread.
  • YouTube can take 24-48 hours to process analytics for videos with few video views or channel followers.
  • TikTok Analytics:
    • TikTok can take 24-48 hours to update their analytics data, such as video views, demographics, likes, shares, and comments.
    • For TikTok analytics access, account owners must: 1. Publish at least one video. 2. Tap the “Turn On” button on the Analytics page of their mobile TikTok app. 3. Have 100 followers to receive additional insights about viewers and content engagement.
    • TikTok does not return post analytics if the media contains copyrighted material or has been flagged for a copyright violation. Examples of copyrighted material can include audio on reels (TikTok will mute these videos). You can check in the TikTok app under Activity -> System Notifications.
    • Some TikTok analytics fields may be unavailable if the video has been inactive for more than 7 days. To retrieve this data, generate new activity on the video (view, like, comment, or share) and retry after 24-48 hours. If a video is not returned in the response, the reason is likely to be that the video has been filtered out due to violations, such as music copyright violation. These fields include:
      • reach
      • fullVideoWatchedRate
      • totalTimeWatched
      • averageTimeWatched
      • impressionSources
      • audienceCountries
  • LinkedIn personal (member) profiles now return an expanded post analytics matrix. The available member metrics are:
    • impressionCount — Impressions on the post
    • uniqueImpressionsCount — Unique members reached (LinkedIn MEMBERS_REACHED)
    • likeCount — Reaction count
    • commentCount — Comments count
    • shareCount — Reshares of the post
    • engagement — Organic clicks, likes, comments, and shares over impressions
    • reactions — Per-type reaction breakdown (when reactions are present)
    • For video posts: videoViews, videoViewers, and videoWatchTimeMs
    Video metrics are only returned for video posts and are unavailable more than one year after the post was created.
  • Instagram Story insights are only available for 24 hours, regardless of whether stories are archived or highlighted. Note:
    • Story media metrics with values less than 5 return as 0.
    • For Stories created by users in Europe and Japan, the replies metric returns a value of 0.
  • Facebook Story analytics are not available.
  • Pinterest analytics data (impressions, user followers, and clicks) becomes available after 24-72 hours.
  • For YouTube Shorts, views will return the number of times a Short starts to play or replay, with no minimum watch time requirement. Starting August 24, 2026, this counting applies to all YouTube video formats, including long-form videos and live streams.

Multiplatform Reads & Partial Success

A single Ayrshare Post ID can span several platforms. Ayrshare fans out one request (“leg”) per platform and returns a partial success when some legs succeed and others fail — the healthy platforms’ analytics are always returned, and each failed leg is enumerated in a top-level errors[] array.
  • Some platforms succeed, some fail: the response is HTTP 200 with status: “partial”. The healthy per-platform analytics blocks are returned as usual, and a top-level errors[] array lists every failed leg with its platform, status, code, message, and id.
  • Every platform fails: the response has status: “error” and the full errors[] array. The HTTP status is mapped from the representative top-level error code. Code 485 maps to HTTP 404; other representative codes use their own mappings.
  • All platforms succeed: the response is unchanged — HTTP 200, status: “success”, and no errors[] key.
Behavior change — inspect errors[], don’t branch on HTTP status. Because a multiplatform read with a failing leg now returns HTTP 200 instead of collapsing the whole response to an error, integrators should always check for the presence of a top-level errors[] array to detect per-platform failures rather than relying on the HTTP status code alone.

Expired or Unavailable Instagram Story Analytics

An Instagram Story analytics leg that is expired or unavailable — so its insights cannot be retrieved — surfaces in errors[] with code 485. A representative message is “Instagram Story expired or unavailable — comments/insights cannot be retrieved.” Facebook Story analytics remain unavailable and are not covered by this behavior. If another platform succeeds, its analytics are still returned and the overall response is HTTP 200. For an all-fail response, representative code 485 maps to HTTP 404; other representative codes use their own mappings. Match on the code (485), not the exact message text. (See also the note above: Instagram Story insights are only available for 24 hours.)

Example: Partial Success Response

200: Partial Success

Daily Post Analytics

Send daily: true with startDate and endDate to get each post’s analytics day by day for that period. Each day carries the last analytics Ayrshare collected for the post that day (UTC), with fetchedAt showing when. Each day’s values are the post’s totals as of fetchedAt, not the activity during that day. Days with nothing collected are left out. Without daily, the request works as described above. A network the profile is not linked to returns error 156, as it does without daily.
With searchPlatformId and postIds, the platform’s value is a list with one entry per post, in the order requested. An X or Threads thread is also a list, with one entry per post in the thread.

Daily analytics for many posts

To get daily analytics for all of a profile’s posts, for example in a daily report:
  1. List the posts with Get History. History filters by publish date, not by when analytics were fetched, so pick a window that holds every post you report on, such as lastDays=90, not the report’s dates. If that window holds more posts than limit returns, split it into shorter startDate/endDate windows. Each post’s Social Post IDs are in postIds[].id, with the network in postIds[].platform.
  2. For each network, call this endpoint with daily: true, the report’s startDate and endDate, searchPlatformId: true, that one network in platforms, and up to 100 of its Social Post IDs in postIds.
A short period, such as the last day, keeps each response small.

Header Parameters

Body Parameters

string
required
Ayrshare Post ID returned from the /post endpoint. This is the top-level Ayrshare id returned and not the social post ids in postIds.
array
String array of platforms to retrieve analytics. Accepts an array of strings with values:
If platforms is not included, analytics will be returned for all social networks to which the post was sent.
boolean
default:false
When set to true, returns the post’s analytics day by day, from the analytics Ayrshare has already collected for it, instead of fetching them from the social network. Requires startDate and endDate. Also works with searchPlatformId and postIds for Social Post IDs. See Daily Post Analytics.
string
Required when daily is true. Start of the period, in ISO 8601 format, for example 2026-10-01T00:00:00Z. Includes analytics collected from this time.
string
Required when daily is true. End of the period, in ISO 8601 format, for example 2026-10-08T00:00:00Z. Includes analytics collected before this time. The period can be at most 31 days.
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.
LinkedIn personal (member) analytics — re-link required. Personal LinkedIn profiles linked before member post analytics shipped do not have the required analytics scopes. Analytics requests for those profiles return error code 475 (“re-link your LinkedIn profile to enable analytics”). The account owner must re-link their LinkedIn profile on the Social Accounts page to grant the new scopes. Allow a few minutes after re-linking for code 475 to clear (Ayrshare and LinkedIn both briefly cache the permission state, typically ~5-10 minutes). Posting is unaffected.LinkedIn member post counts are best-effort: the aggregate shareCount (RESHARE), likeCount (REACTION), and commentCount (COMMENT) totals may differ slightly from the numbers shown in the LinkedIn UI.