analytics

Call analytics.query_metrics

'how many visitors did we get last week?', 'what's our conversion rate?' — read this workspace's analytics numbers over a window: the same figures, from the same reads, the analytics pages show. Name dictionary keys (analytics.list_available_metrics lists them) and a preset period or an explicit from/to; set compare to also read the preceding window. Every row carries a state: empty is a final answer, read_failed means nothing is known, and suppressed means a small-count privacy floor withholds the figure. It changes nothing. Not for which metrics exist or report here — that is analytics.list_available_metrics.

Every result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with workspace_ambiguous and lists the choices — offer them, never pick one.

post/api/v1/tools/analytics.query_metrics

Request

  • Base URL: https://app.goosybear.ai
  • URL: https://app.goosybear.ai/api/v1/tools/analytics.query_metrics
  • Auth: HTTP bearer

Headers

x-request-idstring

Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from A–Z a–z 0–9 . _ : -, starting with a letter or digit; anything else is replaced by a generated id.

Request body

metric_keysstring[] required

Dictionary metric keys to read. Use analytics.list_available_metrics to discover them.

periodstring

The window ending at the start of today (today is excluded), as the span the member names, counted in whole days: 14d for two weeks, 30d for 30 days, 3d for the last three days. Three ids are the analytics page's own presets and read whole COMPLETE periods: 7d = the last 7 complete days, 28d = the last 4 complete weeks, 90d = the last 3 complete calendar months (92 days on a May-Aug read, not 90); use one of them only when the member's span is that one. Any other count, 1d to 366d, reads that many complete days. Omit when supplying from/to, which is for named calendar dates ('in March').

fromstring

Window start, ISO-8601 date or timestamp. Inclusive. Requires to.

tostring

Window end, ISO-8601 date or timestamp. EXCLUSIVE.

grain'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'lifetime'

Granularity the stored rows are read at. LEAVE THIS UNSET unless you have a specific reason: day is where the analytics store is written, and asking for a coarser grain reads a different set of rows that is usually empty. A window is summed from day rows regardless of how long it is, so a month-long window does NOT need grain=month.

compareboolean

Also read the immediately preceding window of the same number of COMPLETE periods, for a like-for-like comparison. On a preset that is a calendar step, so the preceding window holds the same number of weeks or months — not necessarily the same number of days.

by'platform'

Split each ad sum (ads_spend, ads_impressions, ads_clicks, ads_conversions) by ad platform — Meta, Google, LinkedIn, TikTok, Snapchat — each with its state: measured (a figure), quiet (connected, nothing ran), unread (we do not read that platform's spend yet) or not_connected. A platform with no figure is never a zero. Other keys come back unsplit. The split is read on a signed-in member's session only: a call made with an API key answers the unsplit figures and a split_note saying so.

sitestring

Narrow site_* metrics to one of the brand's Pages sites, by its name as the member says it, like Riverside Bakery, or by its id. The name is looked up in this workspace, so no page.list call is needed first. Add page_path for one page of it; a path (it starts with /) is always page_path, never site. Only with site_* keys.

site_idstring uuid

The same narrowing as site, by the site's id alone. Only with site_* keys.

page_pathstring

Narrow site_* metrics to one page by its path, like /pricing — that path on every site unless site is also given. Only with site_* keys.

workspacestring

Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.

Response

The call was admitted and dispatched. ok says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.

OR

Changes

No recorded changes to this operation across all 4 revisions of this API.