Skip to main content
Glama

get_account_analytics

Read-onlyIdempotent

Account-level Instagram insights for a date range: total/daily reach, daily follower count, follows vs unfollows, this-week-vs-last-week totals (views/reach/accounts engaged/interactions/profile link taps), and follower demographics (age+gender, top cities, top countries).

`engaged_audience` has the same three breakdowns for the people who
engaged with the content (followers or not), for Instagram's this_week
and this_month timeframes — compare it with the follower demographics to
tell whether the content reaches a different crowd than the follower base.
It ignores since/until (Instagram only offers those two timeframes), is
empty for accounts under 100 engagements in the timeframe, and can lag by
up to 48 hours.

`breakdowns` splits the selected window's totals: views by follower vs
non-follower (`views_by_follower_type`) and by format
(`views_by_media_product_type`: REEL, POST, CAROUSEL_CONTAINER, STORY,
AD), reach the same two ways (`reach_by_follow_type`,
`reach_by_media_product_type`), and profile link taps by contact button
(`profile_links_taps_by_contact_button_type`). `views_non_follower_share`
and `reach_non_follower_share` (0..1) are the share from non-followers,
the clearest reach-growth signal and a good companion to trial reel
results. Meta marks `views` as in development, so present view counts and
their splits as estimates (`views_is_estimate: true`).

Meta only retains account insights for 90 days — a range extending
further back is clamped automatically (`clamped: true` in the result),
and a range entirely older than that returns empty series with
`out_of_retention: true` rather than an error.

Two ways to pick the window, pick exactly one style per call:

  • days: an integer count ending today, in the workspace's own local time — e.g. days=50 for "the last 50 days". Preferred for relative asks ("last N days", "this month so far") since it does the date math correctly against the account's own clock instead of you computing it.

  • since/until: explicit "YYYY-MM-DD" bounds (inclusive), in the workspace's own timezone (list_workspaces/get_posting_slots show it) — for a specific calendar window ("August 1 to August 15"). Passing days together with since/until is rejected as ambiguous. Omitting all three defaults to the last 30 days.

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": {
      "workspace_id": "<workspace_id>"
    },
    "name": "get_account_analytics"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNo
sinceNo
untilNo
workspace_idYes

Output Schema

NameRequiredDescriptionDefault
rangeYesThe window a response was actually built for. Always echoed so a caller labels the numbers from what came back, not from request state — the 90-day clamp and the cache can both make those differ.
reachYes
citiesYes
clampedNo
followsYes
countriesYes
last_weekYes
this_weekYes
unfollowsYes
age_genderYes
breakdownsNoWindow totals split by audience, format and contact button. Keys inside each split are Meta's dimension values, e.g. FOLLOWER / NON_FOLLOWER for the audience splits, REEL / POST / CAROUSEL_CONTAINER / STORY / AD for the format splits, and EMAIL / CALL / TEXT / DIRECTION / BOOK_NOW / INSTANT_EXPERIENCE / UNDEFINED for contact buttons. An empty dict means Meta returned nothing for that split (or the call failed).
totals_28dYes
follower_countYes
followers_totalYes
engaged_audienceNoWho engaged with the content (engaged_audience_demographics), for Instagram's two supported timeframes. Both are fetched up front so the Account tab's week/month toggle is instant and shares one cache entry. Unlike the account series these ignore the date picker: Meta only offers this_week / this_month. Meta returns nothing for an account under 100 engagements in the timeframe, so empty blocks are normal for small accounts, and the numbers can lag by up to 48 hours.
out_of_retentionNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare this a safe idempotent read, but the description still adds substantial behavior an agent could not infer: 90-day retention with automatic clamping (`clamped: true`), an empty-series-with-`out_of_retention` response instead of an error, engaged_audience being empty under 100 engagements and lagging up to 48 hours, and `views` being flagged as in-development via `views_is_estimate`. These are exactly the non-obvious traits that change how an agent calls and reports results.

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

Conciseness4/5

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

Front-loaded with a clear one-sentence scope statement, and the window-selection rules are set off in a bulleted block that is easy to act on. It is long, and three paragraphs are spent cataloging returned field names (`views_by_media_product_type`, `reach_non_follower_share`, etc.) even though an output schema already exists, which is some redundancy — though the caveats embedded there (lag, estimate flags, emptiness threshold) do earn their place.

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 four-parameter analytics tool with an output schema, the description covers everything an agent needs to call it correctly and interpret edge cases: timezone semantics, window-selection exclusivity, 90-day retention clamping, out-of-retention behavior, view-estimate caveats, and the engaged-audience timeoutframe restriction. Nothing material is left for the agent to discover by trial.

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

Parameters4/5

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

Schema description coverage is 0%, so the description carries the full burden and largely does: days is an integer count ending today in workspace-local time, since/until are inclusive 'YYYY-MM-DD' bounds in the workspace timezone, mutual exclusivity is spelled out, and the all-omitted default is documented. The remaining gap is workspace_id, which is required but never explained (where to obtain it, what it scopes) beyond a passing reference to list_workspaces.

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

Purpose5/5

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

Opens with a specific verb-and-resource statement ('Account-level Instagram insights for a date range') and enumerates exactly which metric families are returned (reach, follower count, follows vs unfollows, week-over-week totals, demographics). The 'account-level' scoping plus the engaged-audience/breakdown comparison cleanly separates it from the per-media siblings such as get_reel_analytics and get_story_analytics without needing to name them.

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?

Gives unusually explicit selection rules for the time window: exactly one of days vs since/until, days 'Preferred for relative asks' because it does the date math against the account clock, since/until for specific calendar windows, and the combination rejected as ambiguous with a documented 30-day default. It does not, however, say when to reach for this tool rather than get_analytics_summary or the reel/story analytics siblings, so tool-level alternatives remain unstated.

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