Skip to main content
Glama
Sign In

supermetrics

by com.supermetrics
OverviewDiscussionsAdmin

instagram_insights

Read-only

Instagram and Facebook (Meta) social media analytics and insights, using the same parameters and result format as data_query. Returns rows when completed; otherwise pass schedule_id to get_async_query_results. Metrics include engagement, engagement rate, reach, accounts reached, accounts engaged, followers, fans, follower growth, impressions, profile and page views, website and link clicks, top posts and best-performing content, content performance, stories, reels, video views, saves, likes, comments, shares, and audience demographics. Data sources (pass one as ds_id):

  • "IGI" — your connected Instagram business/creator account insights (media, reels, stories, top posts, follower demographics);

  • "IGPD2" — public data on any Instagram profile or hashtag (competitor benchmarking, business discovery, hashtag search);

  • "FB" — organic Facebook Page insights (page and post engagement, reach, fans/followers, impressions);

  • "FA" — Facebook & Instagram paid ad performance (Meta Ads); add the "publisher_platform" dimension to separate Facebook from Instagram placements (values include facebook and instagram; filter or segment on publisher_platform = instagram for Instagram-only ad metrics). Then use accounts_discovery to find the account IDs to pass in ds_accounts, and field_discovery to find the available field/metric IDs (and report types) for your chosen ds_id. To create or update Instagram (or Facebook) ad campaigns, use the manage_campaign tool. For any other platform (Google Ads, GA4, LinkedIn Ads, TikTok, and 170+ other data sources), use the data_query tool.

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": {
      "ds_id": "<ds_id>"
    },
    "name": "instagram_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
ds_idYesData source ID from data_source_discovery (e.g. 'FA', 'AW', 'GAWA')
freshNoSkip stored results and run the query again. Use only to confirm a change right after a write, e.g. a budget or status update; it is slower and uses more quota. Only for campaign management data sources (e.g. Facebook Ads, Google Ads). Not available with API keys or for every client; the result notes say when it was not applied.
fieldsNoField IDs from field_discovery, comma-separated. List dimensions before metrics (e.g. 'date,clicks,cost'); if unsure whether a field is a dimension or metric, check field_discovery. All fields must share a common report_type if the source uses report types.
filtersNoFilter expression: field_name operator value, combined with AND/OR. Operators: ==, !=, >, >=, <, <=, =@ (contains), !@ (not contains), =~ (regex), !~ (not regex), [] (in list). Example: "country == US AND clicks > 100"
compressNoAlways recommended. Returns completed rows as a compact text table whose columns are the requested field IDs.
end_dateNoYYYY-MM-DD. Required when date_range_type=custom.
max_rowsNoMax rows to return (default 1000). Higher values may be capped by your license.
settingsNoData source settings from data_source_discovery as a JSON object. Include report_type and all setting_ids here. report_type is a preference when the source picks the report from the fields; some sources treat it as a strict choice and refuse one that does not fit. TikTok Smart+: use platform_details.is_smart_plus in campaign_and_resource_get.
timezoneNoIANA timezone (e.g. 'America/New_York'). Default: UTC.
start_dateNoYYYY-MM-DD. Required when date_range_type=custom.
ds_accountsNoAccount IDs from accounts_discovery, or free-text identifier when is_free_text_account_required=true. Required when has_account_list=true; ALL_ACCOUNTS queries every account of the connected logins: use only when the user asks for all accounts, as it can be slow or rate-limited on sources with many accounts.
compare_showNoperc_change (default), abs_change, or value
compare_typeNoprev_range, prev_year, prev_year_weekday, or custom (with compare_start/end_date)
date_range_typeNoA date range is required for nearly all data sources (is_date_range_required=true in data_source_discovery config). Use a relative range: last_7_days, last_30_days, last_90_days, last_month, this_month, yesterday, etc. (append '_inc' to include the current period), or 'custom' with start_date/end_date. Pass as a root-level parameter, NOT inside settings.
compare_end_dateNoYYYY-MM-DD (when compare_type=custom)
compare_start_dateNoYYYY-MM-DD (when compare_type=custom)

Output Schema

NameRequiredDescriptionDefault
dataNo
errorNo
notesNo
successYes
business_contextNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare readOnly, openWorld, non-destructive, non-idempotent, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results may come back asynchronously with a schedule_id, and the FA source requires the publisher_platform dimension to separate Facebook from Instagram placements. It does not discuss quota/cost or how AL.. account scoping behaves, which the schema covers only indirectly.

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

Conciseness3/5

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

The routing information is front-loaded and the bulleted data-source legend is well structured. However, the 40-item metric enumeration ('saves, likes, comments, shares...') is padded and largely discoverable via field_discovery, adding bulk without changing how the agent calls the tool.

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

Completeness4/5

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

For a 16-parameter, multi-source analytics tool with an output schema and full annotations, the description covers the async fallback path, the discovery prerequisites, the platform-specific dimension for ad data, and the boundaries against sibling tools. Quota/credential caveats are delegated to the schema (fresh), which is acceptable but leaves a small gap.

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 coverage is 100%, so the baseline is 3, but the description meaningfully extends ds_id beyond the schema's generic example ('FA', 'AW', 'GAWA') by defining IGI, IGPD2, FB, and FA and their data domains. It also ties ds_accounts and fields to their discovery tools, adding semantics the schema alone does not establish.

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 the resource (Instagram/Facebook Meta social analytics) and the operation (retrieve metrics/insights), and the enumeration of metrics and the four ds_id families sharpens the scope. It is distinguishable from data_query by the explicit Meta-only framing, though the description is long enough that the core purpose is diluted by the metric list.

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

Usage Guidelines5/5

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

It gives explicit routing rules: use accounts_discovery for ds_accounts, field_discovery for field IDs and report types, get_async_query_results when a schedule_id is returned, manage_campaign for creating/updating Meta ad campaigns, and data_query for every other platform. The ds_id legend (IGI, IGPD2, FB, FA) tells the agent exactly which variant to select per use case.

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

All supermetrics toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources