Skip to main content
Glama

Get a connected account's insights

get_account_insights
Read-only

Account-level insights of ONE connected account: the follower total and its growth for every platform, and what each platform adds. Platforms and the figures each one reports (the activity.series / activity.totals keys; the follower total is followers.current, and followersNow): Instagram (INSTAGRAM): followersCount, followerCount, follows, unfollows, reach, views, accountsEngaged, totalInteractions, likes, comments, saves, shares, replies, reposts, profileLinksTaps; Facebook (FACEBOOK): followersCount; YouTube (YOUTUBE): followersCount; Pinterest (PINTEREST): followersCount, impressions, totalInteractions, saves, pinClicks, outboundClicks; TikTok (TIKTOK): followersCount; Bluesky (BLUESKY): followersCount; Mastodon (MASTODON): followersCount; X (Twitter) (TWITTER): followersCount. Only Instagram (connected through either Instagram Login or Facebook Login) reports reach, views, accounts engaged, follows and unfollows per day and the audience's country, city and age/gender; Pinterest reports a daily series of impressions, totalInteractions (Pinterest's own engagement count), saves, pinClicks and outboundClicks; Facebook, YouTube, TikTok, Bluesky, Mastodon, X (Twitter) report the follower total only, so for them activity, followChanges and both demographics blocks come back NO_DATA, which means the platform does not report that block — it is not a zero and not "yet", so do not promise it will fill in. YouTube rounds its subscriber count down to three significant figures, so a YouTube channel's followers are YouTube's rounded figure, and a channel that hides its subscriber count has none. TikTok means Login Kit accounts (a TikTok Business account is refused). Collected once a day; every platform's follower series starts on the first day PostRite collected the account (for an account connected before account insights shipped, the first nightly run after that, not the day it was connected), so a new account has a single point (Pinterest also backfills the last 30 days of its daily series and stores only days Pinterest has finished counting, a few days late). Instagram: reports with a delay of up to 48 hours, so the latest days can still change (dataLagHours is that Instagram figure); the first collection backfills the last 30 days of reach and of the daily follower change and the last 7 days of views, accounts engaged, interactions, follows and unfollows, while the follower total and the audience start on the first day PostRite collected the account, so a new account has fewer days than the period asked; Instagram reports the follower figures only for accounts with at least 100 followers (minFollowers). Every block (followers, activity, followChanges, demographics.followers, demographics.engaged) is {data, reason}: either its data or the reason it has none (MISSING_PERMISSION, NOT_OFFERED, BELOW_FOLLOWER_THRESHOLD, NOT_COLLECTED_YET, NO_DATA, CONNECTION_INACTIVE, METRICS_OFF, METRICS_PAUSED) — an empty block is NOT zero, so say why it is empty instead of reporting 0. MISSING_PERMISSION and CONNECTION_INACTIVE are fixed by reconnecting the account in PostRite (MISSING_PERMISSION is Instagram's); NOT_OFFERED means PostRite does not request the permission right now, so reconnecting changes nothing; BELOW_FOLLOWER_THRESHOLD is Instagram's rule (followersNow and minFollowers say how far the account is); NOT_COLLECTED_YET resolves after the next daily run, and after the next weekly read for the audience (up to a week); NO_DATA means the platform answered with an empty dataset, or does not report that block at all. METRICS_OFF and METRICS_PAUSED are X's: reading an X account's metrics may add costs to the customer's own X developer account, so it is off until someone turns it on with the switch on the account's card in the app's Platforms page (METRICS_OFF), and X refusing the read (no credit left, or keys without read access) pauses it until someone clicks Resume there (METRICS_PAUSED) — no tool changes either, so tell the user where the switch is; what was collected before stays readable. In activity.series a null metric on a day was not returned, never zero; totals sum the period, and previousTotals the equally long one before only for the metrics whose number of days matches (otherwise null: no comparison). Instagram's reach and accountsEngaged are sums of daily unique counts, higher than Instagram's own period figure, which counts each account once, so never present them as unique accounts for the period. Demographics are an Instagram weekly snapshot (capturedAt, covering the response's timeframe) of the top values Instagram returns, so a share is of the listed values, not of all followers. For the hours an Instagram account's followers are online use get_analytics_insights with this platformConnectionId (audienceActivity). Find the id with list_platform_connections (any platform listed above).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "platformConnectionId": "<platformConnectionId>"
    },
    "name": "get_account_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNoPeriod in days (7, 30, 90; default 30)
organizationIdNoOrganization to act in — an id from list_organizations. Required when this connection was authorized for more than one organization; omit it when there is only one.
platformConnectionIdYesThe account's connection id (from list_platform_connections); a platform without account insights, or a TikTok Business account, is refused

Output Schema

NameRequiredDescriptionDefault
daysNoPeriod length in days
activityNo{series[{date, reach, views, accountsEngaged, totalInteractions, likes, comments, saves, shares, impressions, pinClicks, outboundClicks, …}], totals, previousTotals}: a null metric was not returned, never zero. Which keys a platform fills is the tool description's per-platform list; a platform with no daily series has no activity (NO_DATA)
platformNo
usernameNoThe account's handle
followersNo{current, asOf, change, start, series[{date, followers, gained}]}: the follower total, its change over the period (null with fewer than two figures) and one entry per collected day
periodEndNoYYYY-MM-DD, UTC days
periodStartNoYYYY-MM-DD, UTC days
dataLagHoursNoHow late Instagram reports its figures (Instagram only)
demographicsNo
followersNowNoLatest known follower total; null before the first collection
minFollowersNoFollowers Instagram needs before it reports its follower metrics (Instagram only)
followChangesNo{series[{date, follows, unfollows}], totals, previousTotals}: Instagram only (NO_DATA for every other platform)
lastCollectedDateNoNewest collected day, YYYY-MM-DD; null before the first run
platformConnectionIdNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedOutput schema / properties / activity / properties / reason / description
      Previous value: -"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE; null when data is present. An empty block is not zero"New value: +"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE | METRICS_OFF | METRICS_PAUSED; null when data is present. An empty block is not zero"
    • changedOutput schema / properties / demographics / properties / engaged / properties / reason / description
      Previous value: -"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE; null when data is present. An empty block is not zero"New value: +"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE | METRICS_OFF | METRICS_PAUSED; null when data is present. An empty block is not zero"
    • changedOutput schema / properties / demographics / properties / followers / properties / reason / description
      Previous value: -"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE; null when data is present. An empty block is not zero"New value: +"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE | METRICS_OFF | METRICS_PAUSED; null when data is present. An empty block is not zero"
    • changedOutput schema / properties / followChanges / properties / reason / description
      Previous value: -"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE; null when data is present. An empty block is not zero"New value: +"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE | METRICS_OFF | METRICS_PAUSED; null when data is present. An empty block is not zero"
    • changedOutput schema / properties / followers / properties / reason / description
      Previous value: -"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE; null when data is present. An empty block is not zero"New value: +"Why data is null: MISSING_PERMISSION | NOT_OFFERED | BELOW_FOLLOWER_THRESHOLD | NOT_COLLECTED_YET | NO_DATA | CONNECTION_INACTIVE | METRICS_OFF | METRICS_PAUSED; null when data is present. An empty block is not zero"
  2. First observed

TDQS

A4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the readOnly/openWorld annotations: it discloses 48-hour Instagram lag, 30-day/7-day backfill windows, YouTube's three-significant-figure rounding, TikTok Login Kit restriction, cost implications of X metrics reads, and that METRICS_OFF/PAUSED cannot be changed by any tool. It also enumerates the per-block reason codes and warns that an empty block is not zero, which is exactly the kind of caveat an agent needs before reporting data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single run-on paragraph of roughly 700 words with heavy parenthetical nesting, ordered by platform rather than by importance. The two most actionable instructions (reconnect path, sibling routing) land at the very end. Nearly every sentence carries information, but the size and lack of structure impose a real reading cost when the same caveats could be moved to documentation or the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool this complex, the definition leaves little unsaid: data provenance, freshness, per-platform coverage, reason-code meanings, and remediation paths are all covered, and an output schema exists for the return shape. An agent could call it and interpret every empty or partial response correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and each parameter already carries a useful description (the days enum, when organizationId is required, and the refusal semantics of platformConnectionId). The description reinforces that periods map to platform-specific day coverage but adds little parameter-level meaning the schema does not already contain, so this sits at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific resource and scope: "Account-level insights of ONE connected account: the follower total and its growth for every platform, and what each platform adds." That differentiates it from the post-level siblings, and the closing sentence points to get_analytics_insights for the audienceActivity case. The purpose is clear once extracted, but it is buried under a very long platform-by-platform enumeration rather than stated crisply up front.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete routing: for follower-online hours, use get_analytics_insights with this platformConnectionId, and use list_platform_connections to find the id. It also states prerequisites implicitly (TikTok Business is refused, X metrics require someone to enable the switch, missed permissions need reconnecting). What it lacks is an explicit contrast with adjacent siblings such as get_analytics_summary or get_post_analytics, so the when-not guidance is only partial.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources