MetricsGo API & MCP

Read access to the Meta ads, Google Ads, organic social, YouTube, Google Analytics, Search Console, Shopify and competitor-website data MetricsGo has synced for your organisation — from your own dashboards and backends (REST) or from Claude, Cursor and agents (MCP).

  • REST base URL: https://metricsgo.digygo.com/api/v1
  • MCP endpoint: https://metricsgo.digygo.com/api/mcp
  • API reference: /docs/api/reference · OpenAPI document: GET /api/v1/openapi.json (no auth)
  • Field definitions: data-contract.md, also served by the describe_metrics MCP tool

Keys

An organisation admin creates keys under Settings → API & MCP. A key:

  • is shown once — MetricsGo stores a hash, not the key; lose it and you revoke it and create another
  • belongs to the organisation, not the person who made it; it keeps working after they leave — revoke it there
  • carries scopes (ads:read, social:read, web:read, store:read, finance:read, competitors:read) that gate endpoints, and an optional brand list that gates rows; neither can widen the other
  • looks like mg_live_ followed by 43 characters

Send it as a bearer token on every request:

Authorization: Bearer mg_live_…

Never in a query string, cookie or body — those are rejected, and a key in a URL is a key in someone's logs.

Keys stay on the server

The API sends no CORS headers, deliberately. A key in browser JavaScript is a key handed to every visitor of that page. Your dashboard calls your backend; your backend calls MetricsGo.

Endpoints

All GET. Dates are YYYY-MM-DD calendar days in Asia/Kolkata; a range may not exceed 366 days.

Endpoint Scope Query
/v1/me any —
/v1/clients any —
/v1/ads/overview ads:read from to client? campaignId? adSetId? adId?
/v1/ads/entities ads:read level=campaign|adset|ad from to client? search?
/v1/ads/breakdowns ads:read level entityId from to
/v1/social/overview social:read from to client?
/v1/social/posts social:read from to client? limit? (1–500, default 100)
/v1/social/thumbnail social:read post
/v1/website/overview web:read from to client? compare? limit?
/v1/website/search web:read from to client? compare? searchType? limit?
/v1/website/behaviour web:read from to client? compare? limit? — Microsoft Clarity; see below
/v1/store/overview store:read from to client? compare? limit?
/v1/google-ads/overview ads:read from to client? compare? limit?
/v1/youtube/overview social:read from to client? compare? limit?
/v1/competitors competitors:read client?
/v1/competitors/changes competitors:read from to client? competitor? minSeverity? (1–5, default 1) limit? (1–200, default 50)
/v1/competitors/insights competitors:read client?
/v1/competitors/detail competitors:read competitor
/v1/addons/gokwik store:read client from? to? (default: last 7 days including today)
/v1/addons/zoho-books finance:read client from? to? (default: last 30 days including today) org? (Zoho organization id or all)
/v1/shopping store:read client from? to? (default: last 30 days including today)
/v1/shopping/products store:read client from? to? status? (approved|limited|pending|disapproved) issue? (issue code) search? cursor? limit? (1–200, default 50)
/v1/overview all four client from to compare? (previous|none)
/v1/overview/roster all four from to
/v1/ads/signals ads:read from to client? level? (campaign|adset|ad, default ad) limit? (1–200, default 50)
/v1/ads/pacing ads:read client?

/v1/overview is one brand's Overview page: a health block per supported platform (sources), a card per connected platform with its KPIs, daily volume-versus-outcome series and top campaigns / posts / videos / pages / queries / products, the outcome grid, the movers, up to five Meta signals, the attention list and a competitors card. /v1/overview/roster is the agency roster: one row per brand the key covers with each platform's headline KPI, freshness and health. Both span every surface, so they need every scope (ads:read, social:read, web:read, store:read); a key missing one gets the 403 naming it. The competitors card is included only for a key that also holds competitors:read. Cards and cells are one platform's own numbers in its own currency and day boundary — never summed across platforms — and meta.dataTimezone is null with mixedTimezones true whenever the connected platforms keep different calendars. hrefs in these payloads are app-relative dashboard links.

/v1/ads/signals is the Signals page: Meta campaigns, ad sets or ads whose hook rate, hold rate, landing-page-view rate, CTR, CPC, cost per result, frequency, results or spend moved unusually against their siblings between the range and the previous equal-length period (robust z ≥ 3 and ≥ 10%; no fixed thresholds). /v1/ads/pacing is month-to-date budget pacing for the scoped Meta accounts in the IST calendar month — it takes no range; budget is null, never 0, when no ad-set budget or account spend cap exists.

/v1/clients lists, per brand, every attached source (Meta ad accounts, Pages, Analytics properties, Search Console sites, Shopify stores, Google Ads accounts, YouTube channels), competitorsWatched, a connected map of booleans, and addons — the client add-ons enabled for the brand (gokwik, zoho_books). The add-on endpoints answer only for a brand that is both visible to the key and has that add-on enabled; any other brand is the same 404 as an unknown one. A brand's Microsoft Clarity project shows in clarityProjects and connected.clarity. A null block on an overview (analytics, search, store, ads, youtube) means that source is not connected for the brands in scope — not "no activity". Google Ads days follow the account's timezone and YouTube days are Pacific. Competitor data is read from the competitors' public websites; a competitor on a brand outside the key's reach is the same 404 as an unknown id.

/v1/shopping is Google Merchant Center (the Shopping dashboard) for one brand: its assigned accounts, the catalogue by status with item-level issues, listing performance for the range and Google's price benchmarks. /v1/shopping/products pages through the catalogue with every product's issues; pass nextCursor back as cursor until it is null. Both need store:read — Merchant Center is the store's product feed, the same family as Shopify and the checkout add-on. A visible brand with no Merchant Center account answers connected: false with empty figures (200, not 404), so "not connected" is distinguishable from "no activity".

client is a brand id from /v1/clients. A brand is called a client in the API and MCP tools for backwards compatibility. entityId is the entity's Meta platform id (as shown in Ads Manager) or its id from /v1/ads/entities.

Which brand does a row belong to?

Every row from /v1/ads/entities — and every campaign in /v1/ads/overview — carries its lineage, the same join keys Meta puts on its own objects (account_id, campaign_id, adset_id) plus the names:

{
  "id": "…", "platformId": "120251864157900220", "name": "Paid Webinar Sales Campaign_Aug12",
  "account":  { "id": "…", "platformAccountId": "act_714689862204894", "name": "Sheizen Wellness" },
  "client":   { "id": "…", "name": "Sheizen Wellness" },
  "campaign": null,
  "adSet":    null
}
  • client is how a row is attributed to a brand. An account that is not assigned to a brand still gets a name — the account's own — with client.id null, so grouping by client.name always works.
  • campaign is set on ad-set and ad rows; adSet is set on ad rows. platformId inside them is the Meta id, so you can join to anything you already pull from Meta.
  • To pipe data per brand, either call with client=<id> (one brand per call) or call once without it and group by client.id.

Response envelope

{
  "data": { … },
  "meta": {
    "timezone": "Asia/Kolkata",
    "from": "2026-08-25",
    "to": "2026-08-31",
    "syncedAt": "2026-09-06T07:30:58.194Z",
    "currency": "INR",
    "truncated": false
  }
}

meta.syncedAt is always present: every number is stored data synced by MetricsGo. The API never calls Meta on your behalf, so a request never spends your Meta quota — and never returns anything fresher than the last sync.

Lists are capped at 500 rows. truncated: true means the cap applied; narrow the range or filter by brand.

Errors

RFC 9457 application/problem+json:

{
  "type": "https://app.digygo.com/docs/api/errors#rate_limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "TooManyRequests: 60 requests per minute per key",
  "code": "rate_limited"
}
Status code When
400 validation_failed bad query (errors[] lists each problem)
401 unauthorized missing, malformed, unknown, revoked or expired key
403 forbidden key lacks the endpoint's scope
404 not_found brand or entity outside the key's reach (existence is never confirmed)
429 rate_limited over 60 requests/minute for this key — honour Retry-After
503 unavailable transient; retry after Retry-After

Rate limits

60 requests per minute per key, exact. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds); a 429 adds Retry-After.

Freshness

Ads data syncs hourly (last 3 days re-pulled nightly, 28 days weekly, because Meta restates). Social syncs on the same schedule. Breakdowns are fetched on demand by the dashboard; the API serves the cache and sets stale: true when the dashboard would have refetched.

MCP

The MCP server exposes twenty-five read-only tools: list_clients, get_brand_overview, get_brand_roster, get_ads_overview, get_ads_signals, get_budget_pacing, list_ad_entities, get_ad_breakdowns, get_google_ads_overview, get_social_overview, list_social_posts, get_youtube_overview, get_website_overview, get_search_performance, get_store_overview, get_merchant_center_overview, list_merchant_center_products, list_competitors, get_competitor_changes, get_competitor_insights, get_competitor_detail, get_gokwik_checkout, get_zoho_books_overview, get_clarity_behaviour, describe_metrics. They return the same { data, meta } envelope as REST, validated by the same schemas.

Claude Code — one command:

claude mcp add --transport http metricsgo "https://metricsgo.digygo.com/api/mcp" --header "Authorization: Bearer <key>"

Cursor and other MCP clients — mcp.json:

{ "mcpServers": { "metricsgo": { "url": "https://metricsgo.digygo.com/api/mcp", "headers": { "Authorization": "Bearer <key>" } } } }

Claude.ai, Claude Desktop and ChatGPT — no key needed. Add the connector with the MCP URL and click Connect: the client discovers MetricsGo's OAuth server (/.well-known/oauth-protected-resource/api/mcp → /.well-known/oauth-authorization-server), sends you to sign in, and you approve it on a consent screen naming the app, the permissions and the organisation. The approval appears in Settings → API & MCP as a connected app and can be revoked there. Grants see exactly the brands the approving user can see. Organisations with Claude's "Request headers" beta can still use a key (Authorization: Bearer <key>).

OAuth 2.1 details (for client authors)

  • Authorization code + PKCE (S256 required), resource = https://metricsgo.digygo.com/api/mcp (RFC 8707), tokens are audience-bound to the MCP endpoint and rejected on /api/v1.
  • Client identification: Client ID Metadata Documents (client_id = your https metadata URL) or dynamic registration at POST /oauth/register. Redirect URIs must be https or loopback (http://localhost/127.0.0.1, any port).
  • Endpoints: /oauth/authorize, /oauth/token (form-urlencoded; authorization_code, refresh_token), /oauth/revoke (RFC 7009).
  • Access tokens last 1 hour; refresh tokens 30 days and rotate on every use. Reusing a rotated refresh token revokes the grant.
  • Scopes: ads:read, social:read, web:read, store:read (default when none is asked for: ads:read and social:read). Scope may narrow on refresh, never widen. Competitor tools need no particular scope.

Tip: ask the model to call describe_metrics first. It explains that null means "not reported by the platform" and is never a zero — the most common misreading of this data.

Compliance

You may process this data only on behalf of the business that connected the Meta account, and only for that business. Do not sell, license, aggregate across businesses, or use it to build or augment profiles of individuals (Meta Platform Terms §5).

Microsoft Clarity (/v1/website/behaviour, get_clarity_behaviour)

Behaviour metrics from the brand's own Clarity project: sessions, users, scroll depth, engagement time and the share of sessions with rage clicks, dead clicks, quick-backs, excessive scrolling, JavaScript errors and error clicks (rates 0–1), with a daily series, the pages with the most frustration and device / country / browser / OS / source / channel breakdowns. connected: false means no Clarity project is attached in scope.

  • Clarity's Data Export API serves only the last 24–72 hours and 10 requests per project per day, so there is no history before historyStartsOn (the day the project was connected).
  • Each day is the rolling 24-hour window that ended when MetricsGo synced (06:00 IST daily), filed under that IST date (meta.dataTimezone = Asia/Kolkata). These are not calendar days and do not line up with GA4.
  • meta.freshness follows the same per-asset model as every other surface; data.notes repeats these rules.