analytics

Ayrshare MCP — Analytics

Three analytics tools, split by what they measure and which kind of id identifies the post. Picking the wrong one is the main failure mode in this group, so anchor on the distinction before calling any of them:

• mcp__ayrshare__get_post_analytics — metrics for one specific post sent via Ayrshare: its likes, comments, shares, views, etc. Identify the post by its Ayrshare Post ID (the id returned by mcp__ayrshare__create_post or found via mcp__ayrshare__get_post_history).
• mcp__ayrshare__get_post_analytics_by_social_id — the same per-post metrics, but for a post identified by its native Social Post ID (the network's own id). Use this for posts that did not originate via Ayrshare, or when all you have is the native id.
• mcp__ayrshare__get_social_network_analytics — account/network-level analytics for a connected social network: followers, impressions, views, demographics, and other profile-level numbers (and reach, where the platform provides it). This is the social network account's analytics, not an Ayrshare User Profile's.

All three are profile-scoped: choose the profile with an optional profileKey tool argument or the Profile-Key header (see Auth below; the argument wins when both are set).

Functions

Tool	Purpose	Method + Endpoint	Required inputs	Optional inputs
mcp__ayrshare__get_post_analytics	Engagement metrics for a post sent via Ayrshare	POST /analytics/post	id — the Ayrshare Post ID	platforms (subset of POST_PLATFORMS)
mcp__ayrshare__get_post_analytics_by_social_id	Engagement metrics for a post by its native Social Post ID	POST /analytics/post	id — the native Social Post ID; platform — exactly one of ANALYTICS_PLATFORMS	— (none)
mcp__ayrshare__get_social_network_analytics	Account/network-level analytics (followers, impressions, views, demographics)	POST /analytics/social	platforms — array of POST_PLATFORMS	quarters (1–4), daily (bool), period60Days (bool, TikTok; not with daily), youtube ({ lifetime: bool }), userId (X only), userName (X only)

ANALYTICS_PLATFORMS (for get_post_analytics_by_social_id): bluesky, facebook, instagram, linkedin, pinterest, reddit, snapchat, threads, tiktok, twitter, youtube.

Full input schemas, example payloads, the per-platform metric notes, and example responses are in references/schemas.md.

Auth

All three tools are profile-scoped: choose the profile with an optional profileKey tool argument or the Profile-Key connection header (the argument wins when both are set). To read a specific client's analytics, pass that client's profileKey as the argument, or configure the connection's Profile-Key; with neither set, calls read the account's primary/Business profile. Full model: ../getting-started/SKILL.md.

Exception, get_social_network_analytics userId/userName (Twitter/X): targeting a specific X user by userId (numeric Twitter ID) or userName (handle) instead of the linked account must use the API key only; that lookup is not profile-scoped. Supplying a profileKey (argument or Profile-Key header) alongside userId/userName returns Error 400. All other analytics calls are profile-scoped as above. See references/schemas.md.

Usage guidance

• Choose by scope first, then by id type. "How did this post do" → a post-analytics tool. "How many followers / what's our reach / analytics on our LinkedIn network" → get_social_network_analytics with the platform(s). Post-level and network-level tools are not interchangeable and rarely both needed for one question.
• Pick the post tool by where the post came from:
  • Sent via Ayrshare → get_post_analytics. Pass the Ayrshare Post id returned by mcp__ayrshare__create_post (or found via mcp__ayrshare__get_post_history). Optionally narrow to a subset of platforms. This is the recommended path for any Ayrshare-sent post.
  • Made outside Ayrshare (or you only have the native id) → get_post_analytics_by_social_id. Pass the social network's native post id as id plus exactly one platform from ANALYTICS_PLATFORMS. mcp__ayrshare__get_platform_history is one way to find that native id (the id field), but only for the platforms it covers — it excludes gmb, reddit, and telegram, so for a network it doesn't cover (e.g. reddit, which is an ANALYTICS_PLATFORMS value) take the native id from the platform itself. See the History skill for that workflow.
• Get the id first. For get_post_analytics, look up the Ayrshare id via create_post output or mcp__ayrshare__get_post_history. For get_post_analytics_by_social_id, look up the native Social Post ID via mcp__ayrshare__get_platform_history where it's supported (it excludes gmb, reddit, telegram); otherwise take the native id directly from the platform. If the user only describes a post in prose, resolve the id before calling.
• get_social_network_analytics is the social network account's analytics. Pass the platforms array you want network-level metrics for. Some metrics require platform eligibility (e.g. business/creator accounts). It does not describe an Ayrshare User Profile — it describes the connected social account itself.

Gotchas

• Wrong tool = wrong answer. Post-level vs network-level is the #1 error. get_post_analytics / get_post_analytics_by_social_id are per post; get_social_network_analytics is account/network-level (followers/impressions/views). If the user asks about a post, the network tool will not have post metrics, and vice versa.
• Ayrshare id vs native id picks the tool — they are different tools, not flags. An Ayrshare Post ID goes to get_post_analytics; a native Social Post ID goes to get_post_analytics_by_social_id. Passing a native id to get_post_analytics (or vice versa) returns nothing useful.
• get_post_analytics_by_social_id needs exactly one platform. It takes a single platform value (singular), not an array — the network you're querying the native id on.
• Ownership matters for the Social Post ID tool. The linked account must own the post. Exception: YouTube — querying a non-owned video by social id returns descriptive metadata (title, description, tags, channel title, privacy status, thumbnails) but zeros for all numeric metrics (views, likes, comments, etc.).
• X/Twitter threads via Social Post ID. Query each tweet's Social Post ID individually; thread replies are not automatically included when you query the parent tweet's id.
• Analytics availability varies by platform. Not every network exposes every metric; some require the post to be a certain type or the account to meet platform eligibility. A missing field is often a platform limitation, not a tool failure. (X, for example, withholds non-public/organic metrics for posts not sent by the authorized user.)
• Fresh posts may have no data yet. Metrics lag publication — a post analyzed seconds after going live can legitimately return zeros or empty fields. That is not an error; the data simply hasn't populated. Don't retry in a loop expecting numbers to appear.
• Profile scoping is the profileKey argument or the Profile-Key header. To read a specific client's analytics, pass that client's profileKey as the argument or set the connection's Profile-Key; the argument wins when both are set. (See ../getting-started/SKILL.md.)
• On failure, call mcp__ayrshare__explain_error, then surface it — don't loop. These are reads, but a 4xx (bad id, wrong platform, ineligible account) won't fix itself on retry. Translate the error via mcp__ayrshare__explain_error and present it. 429 gets at most one retry. (Mirrors the global retry-safety rule.)