Skip to main content
POST
Get analytics and demographics on a user’s social profile, such as impressions, views, and followers. Currently available for Bluesky, Facebook Pages, Google My Business, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Threads, TikTok, X/Twitter, and YouTube.
Facebook: some reach and video metrics were retired by Meta (June 15, 2026). Meta removed the unique impression and 3-second video-view (unique) Insights metrics across all Graph API versions, so the Facebook analytics object no longer returns the pagePostsImpressions* family (pagePostsImpressions, pagePostsImpressionsPaid, pagePostsImpressionsUnique, pagePostsImpressionsOrganicUnique, pagePostsImpressionsViral*, pagePostsImpressionsNonviral*, pagePostsServedImpressionsOrganicUnique) or pageVideoViewsUnique. Use pageMediaView for reach (a Total Unique Media Views successor is planned). pagePostEngagements, pageVideoViews, and pageVideoViewsPaid are unaffected. Reference: Upcoming API Changes — June 15, 2026.
  • Facebook Page analytics is only available on Pages with 100 or more likes, such as demographics. Facebook typically updates their metrics once every 24 hours.
  • Instagram may take up to 48 hours to calculate the analytics data. Follower count analytics is not available with fewer than 100 followers. Demographic metrics only return the top 45 performers, only viewers for whom we have demographic data are used in demographic metric calculations, and demographic data is not returned if the Instagram User has fewer than 100 engagements during the last 30 days.
  • When retrieving Instagram social analytics, demographic information may not appear in the response for particular metrics. Demographic information will appear when the metrics have more than 100 people in each breakdown. Please see Instagram Analytics Demographics Warning for more information.
  • LinkedIn supports both Company Page analytics and personal (member) profile analytics. For personal profiles, the analytics object includes a lifetime followersCount, daily follower growth in followersDaily[], and aggregate post metrics (impressionCount, uniqueImpressionsCount, likeCount, commentCount, shareCount). LinkedIn count totals are eventually consistent, but not immediately consistent, and can take up to 24-48 hours in some cases. The aggregate shareCount, likeCount, and commentCount for personal profiles are best-effort and may differ slightly from the numbers shown in the LinkedIn UI.
  • TikTok can take 24-48 hours to update their analytics data, such as video views, demographics, likes, shares, and comments.
  • Please see the post analytics endpoint for additional info.

Header Parameters

Body Parameters

array
required
Social media platforms to get analytics. Accepts an array of strings with values:
integer
Specifies how many quarters of historical data to return. A quarter is:
  • 85 days for Facebook
  • 90 days for Instagram, TikTok, and YouTube
  • 90 days for Snapchat (capped at 1 quarter / 90 days max due to Snapchat API limitations)
Available for Facebook, Instagram, Snapchat, TikTok, and YouTube platforms. Valid values: 1–4. Only values greater than 0 activate date filtering.Date filtering (Instagram & TikTok): Date filtering is active when daily=true OR quarters > 0. If neither daily nor quarters is provided, all-time data is returned with no date filter applied.Note: quarters: 0 is now treated as no date range (all-time data). Previously, quarters: 0 was treated as quarters: 1.
boolean
default:false
When set to true, returns analytics data as daily time-series values instead of aggregated totals. This option is only available for Facebook, Instagram, Snapchat, TikTok, and YouTube platforms. Due to the larger data size, using compression is recommended.For Instagram and TikTok, setting daily=true also activates date filtering using a default shorter quarters window.Instagram reach: With daily=true, the Instagram response returns a nested reach object (containing period and a values time-series) instead of the scalar reachCount field that is returned in non-daily mode.
boolean
default:false
For TikTok analytics, when set to true, this returns only the 60-day aggregate totals for comments, shares, and views (commentCountTotal, shareCountTotal, viewCountTotal). This provides faster response times compared to retrieving the full analytics history. Note: Do not use this parameter together with daily=true as they are incompatible.Important: As of March 1, 2025, TikTok moved to 60-day totals. As of April 2026, TikTok uses quarters-based date filtering — use the quarters parameter to control the date window (e.g., quarters: 1 = 90 days, quarters: 2 = 180 days). See upcoming changes for details.
object
Platform-specific options for YouTube analytics.lifetime (boolean, default: false): When set to true, includes lifetimeLikes in the response - the sum of likes across all public videos on the channel. This is computed by fetching all videos and summing their like counts, so it may take longer for channels with many videos.Threshold: Channels with more than 1,000 videos will return lifetimeLikes: null and a warning in the top-level warnings array. This prevents excessive API usage.Caching: Per-channel, with shorter TTLs for non-success outcomes so retries pick up state changes promptly:
  • Successful lifetimeLikes value: 24 hours.
  • 1,000-video bailout (warning code: 445): 1 hour — short enough that a channel which deletes videos to drop below the threshold doesn’t have to wait a full day for a real value.
  • Transient YouTube Data API failures (warning code: 446): not cached — the next request retries.
Note: Deleted or private videos are excluded from the sum, so the total may differ from the “true” lifetime likes for channels that have removed videos.Request example:
string
X/Twitter only. This parameter allows you to retrieve posts from a specific X/Twitter user by their numeric ID, rather than from your linked account.For example, to get all posts from the handle @Google, you would use their numeric userId 20536157.You can find any X/Twitter user’s numeric userId by using the Brands Get User endpoint.Note: Use only the API KEY in the header to make this request. Do not include the Profile Key.
string
X/Twitter only. This parameter allows you to retrieve posts from a specific X/Twitter user by their handle, rather than from your linked account.For example, to get all posts from the handle @Google.Note: Use only the API KEY in the header to make this request. Do not include the Profile Key.
When cumulative metrics (e.g., followers, likes) 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 reactions: The post-level cumulative reactions metric (an object of per-type reaction counts) is subject to this empty-only backfill. When LinkedIn rate-limits the reactions fetch, the value carries forward from the last successful snapshot — and backfilledFrom is set to that snapshot’s timestamp — instead of regressing to empty.
LinkedIn personal (member) analytics — re-link required. Personal LinkedIn profiles linked before member analytics shipped do not have the required analytics scopes. Social 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.
warnings (array of objects, optional top-level field) — Present only when Ayrshare needs to inform the caller of a non-fatal condition (e.g., an opt-in computation was skipped). Absent from the response when there is nothing to warn about.Each entry is a structured object, not a free-form string:Known warning codes:
  • 445lifetimeLikes skipped because the YouTube channel exceeds the 1,000-video threshold.
  • 446lifetimeLikes unavailable because the YouTube Data API returned errors for the uploads playlist or every videos.list batch.