Workspaces & analytics
list_workspaces
Read onlyWorkspaces you can reach, with your role in each. Call this first: every other tool takes a workspace_id. An access key limited to chosen workspaces lists only those.
REST: GET /api/v1/workspaces or POST /api/v1/tools/list_workspaces
No arguments.
get_distribution_report
Read onlyHow many people reach the workspace's product in a date range: web traffic from its Google Analytics property (users, sessions, channels, key events such as sign-ups) and search demand from its Search Console site (clicks, impressions, position), each with the previous period. `sources` says which of the two are connected; a source that is not connected returns null.
REST: GET /api/v1/workspaces/{workspace_id}/distribution or POST /api/v1/tools/get_distribution_report
3 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
start_date | string | No | YYYY-MM-DD. Default: 29 days before end_date. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
get_analytics_status
Read onlyWhich Google sources the workspace has connected (Google Analytics 4 property, Search Console site) and which analytics tools they unlock. Call this first when an analytics tool says a source is not connected.
REST: GET /api/v1/workspaces/{workspace_id}/analytics or POST /api/v1/tools/get_analytics_status
1 argument
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
get_web_analytics
Read onlyA ready-made Google Analytics 4 report, compared with the previous period. Reports: overview (Headline numbers (users, sessions, engagement, page views, key events, revenue) with a daily series); daily (One row per day); weekly (One row per ISO week); monthly (One row per month); hourly (One row per hour (property time zone)); channels (Sessions by default channel group (Organic Search, Direct, Referral, Paid Social…)); sources (Sessions by source and medium (google / organic, linkedin.com / referral…)); referrals (Sites that send visitors through links); campaigns (Sessions by UTM campaign, with source and medium); acquisition (Where new users first came from (first-touch channel and source)); landing_pages (The first page of each session, with engagement and key events); pages (Pages and screens by views, with users and engagement time); events (Every event by count and users); key_events (Conversions (GA4 key events) such as sign-ups and purchases); countries (Users by country); regions (Users by region and country); cities (Users by city and country); languages (Users by browser language); devices (Desktop, mobile and tablet); browsers (Users by browser); operating_systems (Users by operating system); new_vs_returning (New and returning users); age (Users by age bracket. Needs Google signals; small numbers are withheld by Google); gender (Users by gender. Needs Google signals; small numbers are withheld by Google); site_search (What visitors search for on the site (needs enhanced measurement)); outbound_clicks (Links to other sites that visitors click (needs enhanced measurement)); file_downloads (Files visitors download (needs enhanced measurement)); ecommerce (Purchases, revenue and the shopping funnel); products (Items viewed, added to cart and purchased, with revenue). Every report takes the same simple filters (country, device, channel, source, medium, campaign, page, landing_page, event, hostname). For anything else use run_ga4_report.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/web or POST /api/v1/tools/get_web_analytics
17 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
report | string | No | Which report. Default overview.overview, daily, weekly, monthly, hourly, channels, sources, referrals, campaigns, acquisition, landing_pages, pages, events, key_events, countries, regions, cities, languages, devices, browsers, operating_systems, new_vs_returning, age, gender, site_search, outbound_clicks, file_downloads, ecommerce, products |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period of the same length and the change. Default true. |
limit | integer | No | Rows to return, 1–1000. Default 25. |
country | string | No | Country name as GA4 shows it, e.g. "United States". Comma-separate several. |
device | string | No | desktop, mobile or tablet. Comma-separate several. |
channel | string | No | e.g. "Organic Search", "Direct". Comma-separate several. |
source | string | No | e.g. "google", "linkedin.com". |
medium | string | No | e.g. "organic", "referral", "cpc". |
campaign | string | No | UTM campaign name. |
page | string | No | Page path contains this, e.g. "/pricing". |
landing_page | string | No | Landing page contains this. |
event | string | No | Event name, e.g. "sign_up". |
hostname | string | No | Only these hostnames, for properties that also record previews, localhost or an app. Comma-separate several; "*.example.com" matches example.com and every subdomain. e.g. "www.example.com,example.com". |
run_ga4_report
Read onlyAny Google Analytics 4 report: up to 9 dimensions and 10 metrics by their GA4 API names (activeUsers, sessionSource, customEvent:plan…), with dimension and metric filters, ordering and paging. The same power as GA4 Explorations. list_ga4_fields lists every field, including the property's custom ones.
REST: POST /api/v1/workspaces/{workspace_id}/analytics/web/query or POST /api/v1/tools/run_ga4_report
13 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
dimensions | string[] | No | GA4 dimension names, e.g. ["date", "sessionDefaultChannelGroup"]. Optional. |
metrics | string[] | Yes | GA4 metric names, e.g. ["activeUsers", "keyEvents"]. At least one. |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period and the change. Default false. |
filters | object[] | No | Dimension filters, all must match. Each: {field, match, value | values, not?, case_sensitive?}. match: exact, contains, begins_with, ends_with, regex, partial_regex, in_list. Example: [{"field":"country","match":"in_list","values":["Germany","France"]}]. |
metric_filters | object[] | No | Metric filters applied after aggregation. Each: {field, match, value | values}. match: eq, gt, gte, lt, lte, between. Example: [{"field":"sessions","match":"gte","value":100}]. |
order_by | object[] | No | Sort order. Each: {field, desc?}. As a string: "-sessions,date". Default: first metric, highest first. |
limit | integer | No | Rows, 1–10000. Default 100. |
offset | integer | No | Rows to skip, for paging. Default 0. |
keep_empty_rows | boolean | No | Include rows whose metrics are all zero. Default false. |
get_realtime_visitors
Read onlyWho is on the site right now: active users in the last 30 and 5 minutes, a minute-by-minute series, and breakdowns by country, page, device and event (also city, platform, audience).
REST: GET /api/v1/workspaces/{workspace_id}/analytics/web/realtime or POST /api/v1/tools/get_realtime_visitors
3 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
breakdowns | string[] | No | Default: countries, pages, devices, events.countries, cities, pages, devices, platforms, events, audiences |
limit | integer | No | Rows per breakdown, 1–100. Default 10. |
list_ga4_fields
Read onlyEvery dimension and metric the workspace's GA4 property supports, including its custom dimensions and metrics, with descriptions. Use the names in run_ga4_report.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/web/fields or POST /api/v1/tools/list_ga4_fields
4 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
kind | string | No | Default all.all, dimensions, metrics |
search | string | No | Only fields whose name or description contains this, e.g. "revenue". |
custom_only | boolean | No | Only the property's custom definitions. Default false. |
get_search_performance
Read onlyGoogle Search performance from Search Console, compared with the previous period: clicks, impressions, CTR and average position. Reports: overview (Clicks, impressions, CTR and average position, with a daily series); queries (What people searched for when the site appeared); pages (Pages that appeared in search, by clicks); query_pages (Each query with the page that ranked for it); countries (Searchers by country (ISO 3166-1 alpha-3 codes)); devices (Desktop, mobile and tablet); search_appearance (Rich results, videos, AMP and other result types); daily (One row per day); hourly (One row per hour for roughly the last 10 days (Search Console's hourly data)). Filters: query, exact_query, exclude_query (e.g. your brand), page, exact_page, exclude_page, country, device, search_appearance. For anything else use run_search_console_query.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/search or POST /api/v1/tools/get_search_performance
19 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
report | string | No | Which report. Default overview.overview, queries, pages, query_pages, countries, devices, search_appearance, daily, hourly |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period of the same length and the change. Default true. |
search_type | string | No | Default web.web, image, video, news, discover, googleNews |
sort_by | string | No | Default clicks (position sorts best first).clicks, impressions, ctr, position |
limit | integer | No | Rows to return, 1–1000. Default 25. |
data_state | string | No | all includes the freshest, still-changing days (as the Search Console UI does). Default all.all, final |
query | string | No | Query contains this text. Comma-separate several to match any. |
exact_query | string | No | Query is exactly this. |
exclude_query | string | No | Leave out queries containing this, e.g. your brand name. Comma-separate several. |
page | string | No | Page URL contains this, e.g. /blog/. |
exact_page | string | No | Page URL is exactly this. |
exclude_page | string | No | Leave out pages whose URL contains this. |
country | string | No | Country as an ISO 3166-1 alpha-3 code, e.g. "usa", "gbr", "tur". |
device | string | No | DESKTOP, MOBILE or TABLET. |
search_appearance | string | No | A search appearance type, e.g. "VIDEO" (see the search_appearance report). |
run_search_console_query
Read onlyAny Search Console Search Analytics query: dimensions date, hour, query, page, country, device and searchAppearance in any combination, regex filters, every search type, aggregation by page or property, fresh or final data, and up to 25,000 rows per call with paging.
REST: POST /api/v1/workspaces/{workspace_id}/analytics/search/query or POST /api/v1/tools/run_search_console_query
12 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
dimensions | string[] | No | Optional; none gives totals.date, hour, query, page, country, device, searchAppearance |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period and the change per row. Default false. |
search_type | string | No | Default web.web, image, video, news, discover, googleNews |
filters | object[] | No | All must match. Each: {dimension, operator, expression}. operator: equals, notEquals, contains, notContains, includingRegex, excludingRegex. Example: [{"dimension":"query","operator":"includingRegex","expression":"(?i)pricing|cost"}]. |
aggregation_type | string | No | Default auto.auto, byPage, byProperty, byNewsShowcasePanel |
data_state | string | No | Default all. hourly_all is needed for the hour dimension.final, all, hourly_all |
row_limit | integer | No | 1–25000. Default 1000. |
start_row | integer | No | Rows to skip, for paging. Default 0. |
get_search_opportunities
Read onlyWhere search traffic can grow or is slipping, worked out from Search Console data: striking-distance queries (position 4–20) with the clicks a top-3 spot would add, high-ranking queries with a weak click-through rate (rewrite the title and description), the queries and pages losing or gaining the most clicks against the previous period, and queries where several of your pages compete (cannibalisation). Use exclude_query for brand terms.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/search/opportunities or POST /api/v1/tools/get_search_opportunities
17 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period of the same length and the change. Default true. |
search_type | string | No | Default web.web, image, video, news, discover, googleNews |
min_impressions | integer | No | Ignore queries with fewer impressions. Default scales with the period (20 for 28 days). |
limit | integer | No | Rows per list, 1–100. Default 15. |
query | string | No | Query contains this text. Comma-separate several to match any. |
exact_query | string | No | Query is exactly this. |
exclude_query | string | No | Leave out queries containing this, e.g. your brand name. Comma-separate several. |
page | string | No | Page URL contains this, e.g. /blog/. |
exact_page | string | No | Page URL is exactly this. |
exclude_page | string | No | Leave out pages whose URL contains this. |
country | string | No | Country as an ISO 3166-1 alpha-3 code, e.g. "usa", "gbr", "tur". |
device | string | No | DESKTOP, MOBILE or TABLET. |
search_appearance | string | No | A search appearance type, e.g. "VIDEO" (see the search_appearance report). |
inspect_url
Read onlyGoogle's index status for one page of the site, as Search Console's URL Inspection shows it: whether it is indexed and why not, last crawl, robots.txt and fetch state, Google's chosen canonical against yours, sitemaps that list it, mobile usability and rich results.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/search/inspect or POST /api/v1/tools/inspect_url
3 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
url | string | Yes | The full page URL, on the workspace's Search Console site. |
language_code | string | No | For translated issue messages, e.g. "en-US". Optional. |
list_sitemaps
Read onlyThe sitemaps submitted for the workspace's Search Console site, with when Google last read them, errors and warnings, and how many URLs each lists.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/search/sitemaps or POST /api/v1/tools/list_sitemaps
1 argument
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
get_analytics_summary
Read onlyEverything a traffic dashboard needs in one call: the GA4 overview with the previous period and a daily series (zero-filled, one row per day), top channels (with change), landing pages, referrers, countries, devices and key events; and Search Console totals, daily series, top queries and pages (with change) and opportunities. A source that is not connected comes back with its status instead of failing the call. Optional: include_health adds the tracking health checks.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/summary or POST /api/v1/tools/get_analytics_summary
9 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period of the same length and the change. Default true. |
hostname | string | No | Count only these hostnames in Google Analytics. Comma-separate several; "*.example.com" matches example.com and its subdomains; "auto" uses the site from the GA data stream (or Search Console). Default: every hostname. |
exclude_query | string | No | Leave Search Console queries containing these out (e.g. your brand). Comma-separate several. |
limit | integer | No | Rows per list, 1–100. Default 10. |
include_health | boolean | No | Also run get_tracking_health. Default false. |
get_tracking_health
Read onlyWhether the workspace's analytics can be trusted, as a list of checks (ok, warn, bad, skipped) with what to fix: Google Analytics and Search Console connected and pointing at the same site; GA receiving data; traffic on hostnames other than the real site (localhost, 127.0.0.1, *.vercel.app and *.framer.app previews, app subdomains) with each one's share; no key events set up; automatic events (page_view, session_start, first_visit, user_engagement, scroll) marked as key events; app and sign-in traffic mixed into the site (referrals from accounts.google.com or login hosts, app paths as landing pages); and a high share of "(not set)" landing pages. Returns suggested_filters.hostname to pass to the other reports.
REST: GET /api/v1/workspaces/{workspace_id}/analytics/health or POST /api/v1/tools/get_tracking_health
5 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
hostname | string | No | The real site's hostnames, when the GA data stream does not say (comma-separate; *.example.com allowed). Default: from the data stream, then Search Console. |
get_analytics_portfolio
Read onlyHeadline GA4 and Search Console numbers for every workspace you can reach (an access key limited to chosen workspaces covers only those), each with the previous period and a zero-filled daily series. Use hostname=auto to count only each workspace's own site. Workspaces without analytics say so instead of failing the call.
REST: GET /api/v1/analytics/portfolio or POST /api/v1/tools/get_analytics_portfolio
7 arguments
| Argument | Type | Required | Description |
|---|
period | string | No | A named period. Default 28d. Ignored when start_date or end_date is given.today, yesterday, 7d, 14d, 28d, 30d, 90d, 180d, 365d, this_month, last_month, this_quarter, last_quarter, this_year, last_year |
start_date | string | No | YYYY-MM-DD. Default: from period. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
compare | boolean | No | Also return the previous period of the same length and the change. Default true. |
hostname | string | No | auto: count only each workspace's own site in GA (from its data stream or Search Console). Default: every hostname.auto |
include_health | boolean | No | Also return each workspace's tracking health status and failing checks. Default false. |
workspace_ids | string | No | Only these workspaces (comma-separated ids). Default: all you can reach. |
Outreach
get_gtm_report
Read onlyOutreach results for a date range: funnel (invited, accepted, replied, meetings), campaigns, senders, inbox, pipeline and CRM sync.
REST: GET /api/v1/workspaces/{workspace_id}/gtm-report or POST /api/v1/tools/get_gtm_report
3 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
start_date | string | No | YYYY-MM-DD. Default: 30 days ago. |
end_date | string | No | YYYY-MM-DD, inclusive. Default: today. |
list_campaigns
Read onlyCampaigns in a workspace with status and how many contacts are in each state.
REST: GET /api/v1/workspaces/{workspace_id}/campaigns or POST /api/v1/tools/list_campaigns
1 argument
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
get_campaign
Read onlyOne campaign's sequence (steps and message texts) and progress: contacts per step and status, sends, replies and accepted invitations.
REST: GET /api/v1/workspaces/{workspace_id}/campaigns/{campaign_id} or POST /api/v1/tools/get_campaign
2 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
campaign_id | string | Yes | |
search_contacts
Read onlyFind contacts by name, email or company. Returns ids for other tools.
3 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
query | string | No | Name, email or company. Empty lists recent contacts. |
limit | number | No | Max 50, default 20. |
list_conversations
Read onlyInbox conversations, newest first. Filter to unread or by reply label.
4 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
unread_only | boolean | No | |
label | string | No | interested, not_interested, meeting_booked, out_of_office, referral, … |
limit | number | No | Max 50, default 20. |
get_conversation
Read onlyAll messages in one inbox conversation, oldest first, plus scheduled replies.
2 arguments
| Argument | Type | Required | Description |
|---|
workspace_id | string | Yes | Workspace id from list_workspaces. |
conversation_id | string | Yes | |