Run a custom insight query
query_insightsRead-onlyIdempotent
[read-only] Read-only analytics query: one metric aggregated (median by default) over posts, broken down by up to a few dimensions (platform, weekday, hour, brand, campaign, postType, label:, arm), at a fixed post age window (48h / 7d / 30d / lifetime) so posts are compared fairly. Every row carries its sample size n; platforms that do not report the metric are listed in availability, never counted as 0. Pro plan or higher.
(Wraps POST /api/v2/insights/query.)
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "query_insights"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dateTo | No | ISO date or epoch ms. Default: now. | |
| format | No | csv = the result as a spreadsheet-safe CSV attachment (UTF-8 BOM, CRLF, cells starting with = + - @ are prefixed with '). Without `format`, `Accept: text/csv` also selects CSV. Errors are always JSON. | json |
| metric | No | impressions | |
| window | No | Snapshot age: the metric as it stood 48h / 7d / 30d after publish, or the latest refresh. | 7d |
| brandId | No | A brand id, or "all" (default: every profile you can see). A brand-bound key is always its own brand. | |
| filters | No | ||
| formula | No | Optional (needs the Advanced insights feature): combine up to three series. Each series is a metric + aggregation over the same breakdown, window, interval, filters and range. `expression` (≤ 80 characters) uses A, B, C, numbers, + - * / and parentheses, e.g. "A / B". Rows are joined on their keys; a group missing from any series, or a division by zero, is null. n = the smallest n across series. `metric` defaults to (and must equal) series A's. Referral series can only be split by platform, weekday or hour. | |
| dateFrom | No | ISO date or epoch ms (publish time). Default: 90 days ago; ranges are capped at 400 days. | |
| interval | No | Adds a time series bucketed by publish date. | |
| breakdown | No | Up to 2 of: platform, brand, campaign, experiment, arm, weekday, hour, postType, or label:<key> (e.g. label:cut, label:line, label:source, label:hook, label:series). The multi-valued format key also splits per group: label:format@length, label:format@style, label:format@non_video, label:format@method (a post counts once in each, never twice in one). A post with no source: label (or no length) falls back to how it was made; those rows have `derived` > 0 and a "derived" label, and no label is written. "arm" = the experiment's compareKey and needs filters.experimentId. | |
| aggregation | No | Default median; pooled for the rates engagementRate, ctr and completionRate. A rate is pooled (Σ numerator ÷ Σ denominator), mean, median or count, never sum or p90. Pooled applies to rates only. | median |
| tzOffsetMinutes | No | Offset from UTC for weekday / hour / day buckets (e.g. -300). |