Metric Sensei Admin API

Two APIs, one way of working

Metric Sensei has two public APIs. They do different jobs, but they are laid out the same way and take the same token, so what you learn on one works on the other.

Connect an AI app: /mcp and sign in

AI apps such as Claude and ChatGPT connect to /mcp on either API and sign in with your Metric Sensei account: no token to copy. On the Admin API you choose read only or read and change; on the gateway you pick the client. The app then acts as you, with your own access. A sign-in for one API never works on the other, so connect each one the app should use. Sign apps out in the admin page.

One token for both

Create a personal API token in the admin page (it starts with msat_) and send it as Authorization: Bearer <token>. It acts as you, with your own role, on both APIs. A token names a person, not a client, so on the gateway also say which client you mean with the Metric-Sensei-Client: <client ID> header. A read-only token can read on both and change nothing.

export MS_TOKEN=msat_...

# Admin API: the clients you manage
curl -s https://api.metricsensei.com/clients -H "Authorization: Bearer $MS_TOKEN"

# API/MCP Gateway: the tools you can run for the client acme
curl -s https://gateway.api.metricsensei.com/tools -H "Authorization: Bearer $MS_TOKEN" -H "Metric-Sensei-Client: acme"

The gateway also takes a gateway API key (mcpgw_), which belongs to one client and needs no header.

The same on both

• REST lives at the root of the address, AI apps connect at /mcp, and this guide is at /docs.
• Without a version you get the latest. Put /v<N> first in the path, or send Metric-Sensei-Version: <N>, to stay on one version; /versions lists them.
• Answers are JSON. Errors have an error code and a plain message.

Getting started

The Admin API lets you manage your agency and clients from your own code: clients and their people, data sources and connections to Google Analytics 4, Tag Manager, Search Console, Business Profile, Merchant Center, Ads, AdSense, PageSpeed Insights, Shopify, Meta Ads, Facebook Pages, Instagram and Meta Business, API/MCP Gateway keys, connected apps, sign-in settings, website tracking and billing. Anything an agency or client admin can do in the admin page you can do here. There are 264 operations, and AI agents can use the same operations as MCP tools.

Using an AI app such as Claude or ChatGPT? Add https://api.metricsensei.com/mcp as a remote MCP server and sign in when it asks: no token needed. See AI agents (MCP). For scripts, start here:

1. Create a token

Sign in to the admin page, open Admin API keys (bottom of the left menu), and choose Create Admin API key. Pick Read only or Read and change and how long it lasts. Copy the token now: it starts with msat_ and is shown only once.

2. Make a call

export MS_TOKEN=msat_...

curl -s https://api.metricsensei.com/me -H "Authorization: Bearer $MS_TOKEN"

That shows your clients, your role in each, the connections you can use, and which token you called with. Then, for example:

# List clients
curl -s https://api.metricsensei.com/clients -H "Authorization: Bearer $MS_TOKEN"

# Invite someone to a client as a client admin
curl -s -X POST https://api.metricsensei.com/clients/acme/users \
  -H "Authorization: Bearer $MS_TOKEN" -H "Content-Type: application/json" \
  -d '{"email": "dana@example.com", "manager": true}'

# Give them read access to one connection
curl -s -X PUT https://api.metricsensei.com/clients/acme/users/USERNAME/access \
  -H "Authorization: Bearer $MS_TOKEN" -H "Content-Type: application/json" \
  -d '{"grants": {"ga4/main-site": "read"}}'

# Let them see GA4 and manage Shopify connections in the admin (separate from the grants above)
curl -s -X PUT https://api.metricsensei.com/clients/acme/users/USERNAME/access \
  -H "Authorization: Bearer $MS_TOKEN" -H "Content-Type: application/json" \
  -d '{"grants": {"ga4/main-site": "read"}, "services": {"ga4": "read", "shopify": "write"}}'

Any OpenAPI tool can read the spec: import https://api.metricsensei.com/openapi.json into Postman, Insomnia or a client generator.

Tokens and sign-in

Every request needs a personal API token in the Authorization header:

Authorization: Bearer msat_...

The same token works for every version. On /mcp, AI apps can instead sign in with your Metric Sensei account (OAuth): see Sign in from an AI app.

• A token acts as you. It has the role you have in the admin page right now. If your role changes or your account is disabled, your tokens follow at once.
• Read only or read and change. Read-only tokens can call GET operations only. Agents with a read-only token see only the read tools.
• Tokens always expire, after 1 to 365 days (90 by default). You can have up to 20.
• Revoke a token in the admin page. It stops working at once.
• API keys are changed only in the admin page. For security, this API can list your tokens and API/MCP Gateway keys (never their secret values) but can't create, change or revoke any of them. In the admin page, creating or revoking a key needs you to confirm it's you with your passkey or authenticator code first.
• Your password, authenticator app and passkeys are changed only on the admin page's Profile tab, which uses your own sign-in. A token can read your profile (GET /me/profile) and change your details: first and last name, phone and address (PATCH /me/profile). They are all required. time_zone sets where the admin page shows dates and times (for example America/Chicago, or empty for your browser's time zone); the API always gives times in UTC.

Roles

A client user has two separate kinds of access, both set with set_user_access: connection grants (grants) decide which data they can use through the API/MCP Gateway and their API/MCP Gateway keys; admin service access (services) decides what they can see and change per service in the admin and this API. Neither gives the other.

Every client belongs to one agency, which owns it and is billed for it. A customer with a single client has a solo agency of its own. The admins of a solo agency run its agency-level work, such as turning services on and managing billing (a customer's first admin becomes one when they accept their invite). To manage more clients, they can upgrade it to an agency account (Settings › Account type, or POST /agencies/{agency_id}/upgrade); its admins then become the agency's admins.

Each operation below says who can use it. Calls outside your role get 403.

Billing

Each agency is on a billing plan. On the Standard plan, each client pays a monthly base fee for every service it has on (charged by the day), plus usage above what the fee includes. On a cost plus plan there are no base fees: every unit used is charged at our cost plus the plan's markup. On the 1st, each agency gets one invoice for the month before, broken down by client, and its default saved card is charged. Unpaid invoices are retried daily, up to three times.

See the agency's plan and the plans you can choose with GET /agencies/{agency_id}/plans, and switch with PUT /agencies/{agency_id}/plan. Your switch starts on the 1st of next month; until then the current plan applies. Some plans can only be assigned by Metric Sensei; an agency on one of those can't switch itself.

To save a card through the API, get a token from GET /agencies/{agency_id}/card-form-token, collect the card with Braintree's client SDK (Hosted Fields or Drop-in), and send the nonce it returns to POST /agencies/{agency_id}/cards. Card numbers never reach Metric Sensei.

Activity (audit) log

Every change is recorded, by every role: who made it, when, in which role, where (the admin page and its service screens, this API, an AI app through the API/MCP Gateway) and with which API token or API/MCP Gateway key. So is every sign-in and every super admin log-in to a client or agency. Normal reads are not recorded. Secrets such as credentials and keys are never recorded. Entries are kept for a year.

• GET /clients/{client}/activity: one client's log (its admins).
• GET /agencies/{agency_id}/activity: an agency's log, including its clients (agency admins).
• GET /me/activity: your own sign-ins and changes (everyone).
• GET /audit: the audit log scoped to you. Super admins see everyone's, including platform settings and deploys; agency admins see their agency's trail including its clients; client admins see their client's; anyone else sees only their own.

All four are newest first, paged like other lists, and take the same filters: actor (an email), via, kind (change, sign-in, session for a super admin log-in, deploy), action, role, since and until (dates, UTC) and q, a text search in which every word must appear. /audit also takes client and agency, which must be ones you can see. A narrow search of a super admin's /audit may return a short page with a next_cursor: keep paging until it is null.

curl -s "https://api.metricsensei.com/clients/acme/activity?limit=20&q=google+ads" -H "Authorization: Bearer $MS_TOKEN"
# {"activity": [{"at": "...", "actor": "dana@example.com", "summary": "turned off Google Ads", "kind": "change", "via": "page", ...}], "next_cursor": null}
curl -s "https://api.metricsensei.com/me/activity?kind=sign-in&since=2026-11-01" -H "Authorization: Bearer $MS_TOKEN"

Usage

See how many API/MCP Gateway tool calls a client made, per day and per service, with GET /clients/{client}/usage?days=30 (1 to 90 days, today included, in UTC). Successful calls are the ones billed; failed calls are counted separately and never billed. month compares this month's calls with the free calls the base fee includes. GET /agencies/{agency_id}/usage lists every client of an agency, busiest first.

curl -s "https://api.metricsensei.com/clients/acme/usage?days=7" -H "Authorization: Bearer $MS_TOKEN"
# {"totals": {"count": 412, "by_service": {"ga4": 300, "gtm": 112}, "failed": 3}, "days": [...], "month": {"count": 1290, "included": 40000}}

Home summary

Read the numbers on a client's or an agency's Home with GET /clients/{client}/summary and GET /agencies/{agency_id}/summary. There is one entry in tiles per Home tile, only for the paid services that are on: API/MCP Gateway calls per day for the last 30 days, Attribution sessions, form submits and people identified, data sources and how many need a new sign-in, live events received, Dashboards and AI Services usage this month. An agency's summary adds each service up over its active clients and includes its free trial (while one runs) and its bill. A client's share of this month's bill (client_bill) is for its agency's admins. Add tiles=gateway,attribution to read only some tiles. A tile that couldn't be read has an error instead of data.

curl -s "https://api.metricsensei.com/clients/acme/summary?tiles=gateway" -H "Authorization: Bearer $MS_TOKEN"
# {"home": "client", "period": "2026-11", "tiles": [{"key": "gateway", "data": {"calls": 412, "failed": 3, "daily": [...], "connections": 4, "api_keys": 2}}]}

Tracked sites

A client's websites, iOS apps, Android apps and APIs are tracked sites, shared by services the way data sources are. Each has a kind (website, ios_app, android_app or api), the services turned on for it, and each service's settings. A website gets one snippet; its tag loads only the code of the services turned on for it (and on for the client). Apps and APIs are identified by their site ID. Today the only service is Attribution, for websites.

curl -s -X POST "https://api.metricsensei.com/clients/acme/tracked-sites" -H "Authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" -d '{"kind": "website", "domain": "acme.com", "services": ["attribution"]}'
# {"site_id": "MS-7KQ2M9XP", "kind": "website", "services": ["attribution"], "running": ["attribution"], "snippet": "<script>...", ...}
curl -s -X PATCH "https://api.metricsensei.com/clients/acme/tracked-sites/MS-7KQ2M9XP" -H "Authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" -d '{"settings": {"attribution": {"debug": true}}}'

settings merges per service, and a service's settings are kept while it is off. The older /clients/{client}/attribution/sites endpoints still work: they show the websites with Attribution on.

Custom tracking domains

A website can load its tag, its code and visitor IDs from a host on its own domain, like t.acme.com, instead of our CDN. Ad blockers then treat it as part of the website, and visitor IDs are also kept in a cookie that host sets on the website's domain, which browsers keep longer than cookies set by page scripts. Set it up, add the four NS records from the answer at the domain's DNS provider, and it goes live by itself (we check every hour; .../domain/check checks now). The snippet then loads from the new host, and the old snippet keeps working.

curl -s -X PUT "https://api.metricsensei.com/clients/acme/tracked-sites/MS-7KQ2M9XP/domain" -H "Authorization: Bearer $MS_TOKEN" \
  -H "content-type: application/json" -d '{"host": "t.acme.com"}'
# {"available": true, "domain": {"host": "t.acme.com", "status": "waiting_for_dns",
#   "records": [{"name": "t.acme.com", "type": "NS", "value": "ns1.ns.metricsensei.com"}, ...], ...}}
curl -s -X POST "https://api.metricsensei.com/clients/acme/tracked-sites/MS-7KQ2M9XP/domain/check" -H "Authorization: Bearer $MS_TOKEN"
# status: waiting_for_dns -> issuing_certificate -> connecting -> active (or failed, with a message saying what to fix)

DELETE .../domain moves the tag back to our CDN first, so the website keeps working.

Looking up a visitor

Admins of a client can look up everything Attribution knows about one visitor: by browser, device, person or household ID (32 characters, as the website tag gives them out), email address, phone number, IP address, or another platform's ID pasted as it is (every ID type we collect is tried, and matched_ids says which matched; write _ga=GA1.1.123.456 to search one cookie only). Emails and phone numbers are hashed before searching, the same way the tag hashes them. The answer has the linked browsers, people and households, other platforms' IDs, hashed contact details, websites, visits, where visits came from, and recent activity. Only that client's visitors are searched. Looking someone up is not logged.

curl -s "https://api.metricsensei.com/clients/acme/attribution/lookup?q=ann@example.com" -H "Authorization: Bearer $MS_TOKEN"
# {"query": {"kind": "email", ...}, "found": true, "matched": ["person"], "people": [...], "browsers": [...], ...}

When a website has keep_contact on (with Attribution's contact capture), the tag also sends one readable copy of the contact details it hashes, encrypted in the visitor's browser. Our servers store only the encrypted copy; it is decrypted for the answer's people[].readable and never stored readable. days (1 to 95, default 95) limits how far back the visit history goes.

Ad-driven lift

A standard Analytics report: the direct visits, organic-search visits and branded searches a client's ads brought (people who saw an ad, then typed the address or searched), by ad channel (Google Ads YouTube, Display/Demand Gen/PMax, Search; Meta; MNTN TV) and by campaign, with extra visits, share, cost per extra visit and a confidence for each. Visits are the website's own Analytics numbers; ad accounts and search sources (Search Console, Google Ads, Microsoft Advertising) are read with your own access, so use a personal token. Brand terms, ad accounts and flights bought elsewhere are the website's Analytics settings (ad_lift, saved with the website); query parameters override them for one request. Websites that also run Attribution add the visits that came back after an ad click, per campaign. It replaced the TV impact report and its operations. It is a correlation, not proof: MNTN's holdout tests are on the gateway's mntn_incrementality tool. When the answer has retry, Microsoft is still building its report: call again about 20 seconds later with ms_ads_report_id from it.

curl -s "https://api.metricsensei.com/clients/acme/analytics/sites/MS-AB12CD34/reports/ad_lift?range=last_90_days&compare=previous" \
  -H "Authorization: Bearer $MS_TOKEN"
# {"summary": "Ads brought about 412 direct visits (6.1%) ...", "by_channel": [...], "by_campaign": [...]}
curl -s "https://api.metricsensei.com/clients/acme/analytics/sites/MS-AB12CD34/reports/attribution?range=last_month" \
  -H "Authorization: Bearer $MS_TOKEN"   # people, devices, form submits by channel, visits after ad clicks

Versions

Every deploy of the API is a new version, numbered 1, 2, 3 and so on. Old versions keep working, so an integration you pin to a version behaves the same until that version is retired.

• Latest: without a version you always get the newest one: https://api.metricsensei.com/clients, https://api.metricsensei.com/mcp.
• Pin with the path: put /v<N> first: https://api.metricsensei.com/v2/clients, https://api.metricsensei.com/v2/mcp.
• Or pin with a header: Metric-Sensei-Version: 2.
• Every response says which version answered, in the Metric-Sensei-Version header.
• Each version has its own docs and spec: /v<N>/docs and /v<N>/openapi.json.
• When an old version can't be kept working any more, it is retired and answers 410 Gone. GET /versions lists every version and its status.

Requests, lists and errors

• Send and receive JSON (Content-Type: application/json). Bodies are at most 64 KB.
• Everything a client owns is under /clients/{client}, and everything an agency owns under /agencies/{agency_id}.
• Deletes answer 204 No Content with an empty body.
• Changes are logged with your username and the token's ID.
• Credentials you send (service account keys, client secrets) are stored in AWS Secrets Manager and never returned.
• Calls are rate limited. On 429, wait a moment and retry.

Lists

List operations return one page: up to limit items (default 100, max 500) and a next_cursor. To get the next page, call again with cursor set to it. On the last page next_cursor is null.

curl -s "https://api.metricsensei.com/clients?limit=50" -H "Authorization: Bearer $MS_TOKEN"
# {"clients": [...], "next_cursor": "NTA"}
curl -s "https://api.metricsensei.com/clients?limit=50&cursor=NTA" -H "Authorization: Bearer $MS_TOKEN"

Errors

Errors have a stable error code, a message for people, and a request_id (also in the X-Request-Id header of every response) to quote if you contact us:

{"error": "forbidden", "message": "You can't manage that client.", "request_id": "c0ffee12"}

AI agents (MCP)

AI apps and agents connect to https://api.metricsensei.com/mcp (MCP Streamable HTTP). They either sign in with your Metric Sensei account, or send a personal API token. Each operation in the reference is a tool with the same name, for example list_clients or invite_client_user. Read tools are marked read-only and delete tools destructive, so agents can ask before changing anything.

Sign in from an AI app

Apps that support sign-in for remote MCP servers (Claude, ChatGPT, Claude Code, Cursor, VS Code and others) need only the address. You sign in on Metric Sensei's login page (with your passkey or authenticator code) and choose Read only or Read and change. The app then acts as you, with your current role, like a token with that access.

• Claude (claude.ai, Desktop and mobile): Settings → Connectors → Add custom connector, paste https://api.metricsensei.com/mcp, then Connect.
• Claude Code: claude mcp add --transport http metricsensei-admin https://api.metricsensei.com/mcp, then run /mcp and choose Authenticate.
• Other apps: add a remote server with the Streamable HTTP transport and choose OAuth sign-in. No client ID is needed: apps find the sign-in through https://api.metricsensei.com/.well-known/oauth-protected-resource/mcp and register themselves (dynamic client registration, PKCE).

Signed-in apps act as you until you sign them out. They are listed by list_my_connected_apps (with api admin) and in the admin page under Connect an AI app › My connected apps. Sign one out with sign_out_my_admin_api_app or the admin page; it stops working at once. Sign-in works on /mcp only; REST calls use a token. The same login also signs AI apps in to the API/MCP Gateway's /mcp, but a sign-in for one API never works on the other.

With a token (Claude Code)

claude mcp add --transport http metricsensei-admin https://api.metricsensei.com/mcp \
  --header "Authorization: Bearer msat_..."

With a token (Cursor, VS Code and other clients)

Add a remote (HTTP) server with an Authorization header. For example in mcp.json:

{
  "mcpServers": {
    "metricsensei-admin": {
      "url": "https://api.metricsensei.com/mcp",
      "headers": { "Authorization": "Bearer msat_..." }
    }
  }
}

Tips for agents: start with get_my_access; use list_client_users or list_agency_users to find a username; start_data_source_sign_in returns a link the person must open.

Connecting Google, Shopify, Meta, WordPress, CallRail, Microsoft, Supermetrics, MNTN, NetSuite, TechShip, Mailchimp, Gorgias and Blazeo

Credentials live in a client's data sources: one per Google account, Shopify store, Facebook or Microsoft sign-in, WordPress site, or CallRail, Bing Webmaster or Supermetrics API key, as many as you need, each with a name you choose. Services then use a data source through a connection, which holds the service's own settings.

Two ways to add a data source:

• Sign in: POST /clients/{client}/data-sources/{source}/sign-in with type (google, shopify or meta) returns a url. For Google, uses picks the services to ask permission for (ga4, gtm, gsc, gbp, merchant, ads, datamanager; default ga4 and gtm); for Meta, uses picks from meta_ads, facebook, instagram and meta_business (default all four); for Shopify, send the shop. Open the link in a browser and sign in to Google or Facebook, or approve the Shopify app. Facebook asks which businesses, Pages, Instagram accounts and ad accounts to share. The data source is saved when you finish. The link works once and expires.
• Shopify tracking: add "tracking": true to a Shopify sign-in to also ask for the pixel's permissions. When the store owner approves, the store's tracked website (its main domain) is created or reused and the Metric Sensei pixel is turned on. Turn it on or off later with PUT / DELETE /clients/{client}/data-sources/{source}/shopify-tracking. The pixel follows the website's custom tracking domain when one is set up. Store owners can also install the Metric Sensei app from Shopify and pick the client in the admin page.
• Paste credentials: PUT /clients/{client}/data-sources/{source} with type and a service account key or Shopify token in credentials.
• Install app: WordPress sites, Shopify stores, HubSpot, Gorgias and Klaviyo accounts and Salesforce orgs have a Metric Sensei app. Choose Install the Metric Sensei app when adding the data source, or POST /clients/{client}/data-sources/{source}/app, and open the link it returns. WordPress (site_url): an administrator of the site presses Approve on WordPress's own Authorize Application screen; Metric Sensei then installs and turns on the plugin, connects it, adds the tracking tag and, with auto_update (on by default), lets WordPress update the plugin by itself. If the site can't install plugins over its REST API, the data source is still saved: download the plugin, upload it under Plugins › Add New › Upload Plugin, then press Finish setup in the source's App dialog (POST .../app/update). Shopify: the store's approve screen (Shopify updates the app and its pixel by itself; App shows when the store must approve new permissions). HubSpot: the account's install link (HubSpot updates the app by itself; App shows missing scopes; until our Marketplace listing is approved HubSpot allows 25 installs). Gorgias (domain): the account's approve screen for an admin (Gorgias runs the app; App shows a sign-in that stopped working or missing permissions). Klaviyo: the account's authorize link (the app lives in Klaviyo, so it is always current; App shows when it was uninstalled or is missing permissions). Salesforce: our package's install link for a Salesforce admin, then sign in. App (GET .../data-sources/{source}/app) shows whether the app is installed and current; for Salesforce, Update installs the newest package version with the data source's sign-in when that user may install packages, otherwise it gives the install link for a Salesforce admin.
• WordPress: use Install app (above), or install the Metric Sensei plugin on the site and press Connect under Settings › Metric Sensei. It opens /connect/wordpress on this page, where you pick the client; with the API, pass the link's site, callback, state and challenge to POST /clients/{client}/wordpress/approve and open the redirect_url it returns. The plugin then saves a wordpress data source and connection and a tracked website, and adds the tag to every page (switching to the site's custom tracking domain when one goes live). You can also paste a site address, username and Application Password with PUT .../data-sources/{source} (type wordpress). With WPForms, Gravity Forms, Contact Form 7, Ninja Forms, Formidable, Fluent Forms, Forminator or Elementor Pro on the site, the plugin (1.1.0+) saves each accepted submission with its traffic source, only accepted submissions are counted on the Attribution dashboard, and AI apps can read forms and entries with wordpress_list_forms and wordpress_list_form_entries.
• CallRail: in CallRail open Settings › Integrations › API Keys and create an API v3 key. On the Data Sources tab choose CallRail and paste the key; with the API, send PUT .../data-sources/{source} with type callrail and api_key. The key is tried with CallRail before it is saved. One key reaches every account and company its CallRail user can see, so press Accounts (or send allowed, for example {"callrail": ["company:COM123"]}) to limit it to one client's company. Then add a callrail connection: its tools read calls, tracking numbers, form submissions, texts, tags and call reports, and, with changes allowed, tag or annotate calls, add tags and send texts (each asks for confirm=true first).
• Snapfulfil: Snapfulfil gives you an API address (https://<name>.snapfulfil.net, one for live and one for test) and sets up an API user for it (Snapfulfil › Users › Permissions: the API host and your Biz). On the Data Sources tab choose Snapfulfil and enter the address, username and password; with the API, send PUT .../data-sources/{source} with type snapfulfil, api_url, username and password. The sign-in is tried before it is saved. Press Accounts (or send allowed, for example {"snapfulfil": ["biz:BIZ1"]}; levels biz > owner) to limit it to one client's business or stock owner. Then add a snapfulfil connection: its tools read shipments, sales and purchase orders, receipts, returns, stock totals and locations, products, customers, suppliers, 3PL invoices, open and closed summaries, warehouse tasks and lookup codes, and, with changes allowed, create, update or delete shipments, sales and purchase orders, receipts, customer returns, products, customers and suppliers, change a shipment's status (hold or cancel) or its tracking and reference fields (each asks for confirm=true first; a record's Biz can't change, and a limited data source only writes inside its Bizs). For live despatch, receipt and stock-move events, open Live events and send the address shown to the Snapfulfil Service Desk; Snapfulfil signs nothing, so keep it private. Shipments are linked to visitors by the web store's order number.
• Microsoft Advertising (Bing Ads): on the Data Sources tab choose Microsoft Advertising › Sign in with Microsoft; with the API, POST .../data-sources/{source}/sign-in with type microsoft_ads. Sign in with a Microsoft account that has a Microsoft Advertising user. It reaches every customer (manager account) and ad account that user can, so choose which ones with Accounts (or allowed, for example {"microsoft_ads": ["account:123456"]}; levels customer > account). Then add a microsoft_ads connection: its tools list accounts, campaigns, ad groups, ads, keywords, budgets, conversion goals and UET tags and run performance reports (account, campaign, ad group, keyword, search terms, geography); with changes allowed they create paused campaigns, pause or turn on campaigns, ad groups and keywords, change budgets and bids, and add keywords and negative keywords (each asks for confirm=true first). The sign-in is renewed by our daily check, so it keeps working as long as the Microsoft account keeps access.
• Bing Webmaster Tools: in Bing Webmaster Tools open Settings › API access › API Key and generate a key. On the Data Sources tab choose Bing Webmaster Tools and paste it; with the API, send PUT .../data-sources/{source} with type bing_webmaster and api_key. The key is tried before it is saved and reaches every site in that Bing Webmaster account, so limit it with Accounts (or {"bing_webmaster": ["site:https://www.example.com/"]}). A bing_webmaster connection reads Bing search queries, top pages, clicks and impressions, crawl stats and issues, URL info, inbound links, sitemaps and keyword research, and, with changes allowed, submits URLs and submits or removes sitemaps (each asks for confirm=true first).
• Supermetrics: reaches the 170+ platforms your Supermetrics team has signed in to (Google Ads, Facebook Ads, LinkedIn, TikTok and more). In Supermetrics Hub create an API key (the team needs Supermetrics' API product). On the Data Sources tab choose Supermetrics and paste it; with the API, send PUT .../data-sources/{source} with type supermetrics and api_key. The key is tried before it is saved. If the key can't list the team's logins, also send connectors (connector IDs, for example ["AW", "FA"]). Press Accounts (or send allowed, for example {"supermetrics": ["connector:FA", "account:AW/1234567890"]}) to limit it to chosen connectors or accounts. Then add a supermetrics connection: its tools list connectors, accounts and fields and run reports. It only reads; nothing is changed in Supermetrics.
• MNTN (Mountain): Performance TV (connected TV) campaigns. In MNTN open My Account › API and copy the Reporting API key (anyone on the MNTN account can see it; Rotate key turns the old one off). On the Data Sources tab choose MNTN (Mountain) and paste it; with the API, send PUT .../data-sources/{source} with type mntn and api_key. The key is tried before it is saved. Press Accounts (or send allowed, for example {"mntn": ["campaign:12345"]}; levels advertiser > campaign) to limit it to chosen advertisers or campaigns; a limited data source's tools must then name the advertiser or campaigns they read. Then add an mntn connection: its tools list advertisers, campaigns and report columns, show performance (spend, impressions, households reached, verified visits, conversions, revenue, ROAS) by day, campaign, creative or channel, list individual conversions with their order and lead IDs, show attribution paths, run any report and start CSV exports for large ones. It only reads; visitor IPs and street addresses are never fetched. MNTN's data is about 36 hours behind. To see which campaign sent a visitor in Attribution, add mntn_campaign_id=${cagid}&mntn_ad_id=${crid} to the ads' visit URL tracking in MNTN.
• Oracle NetSuite: customers, leads, contacts, sales orders, invoices and sales totals, through NetSuite's machine-to-machine sign-in (nobody signs in again; a certificate lasts up to two years). A NetSuite administrator of the client's account turns on REST Web Services and OAuth 2.0 (Setup › Company › Enable Features › SuiteCloud), makes a role for us (read-only is safest) and a user with it, and makes an integration record with the Client Credentials (Machine to Machine) grant and the REST Web Services scope. On the Data Sources tab choose Oracle NetSuite and enter the account ID and the integration's client ID; with the API, send PUT .../data-sources/{source} with type netsuite, account_id and client_id. We make a certificate: upload it in NetSuite (Setup › Integration › OAuth 2.0 Client Credentials Setup, mapped to that user, role and integration), then save the certificate_id NetSuite shows (it is tried before it is saved). GET .../netsuite shows where setup stands; POST .../netsuite/certificate makes a new certificate before the old one expires (the data source warns a month ahead). Press Subsidiaries (or send allowed, for example {"netsuite": ["subsidiary:3"]}) to limit a OneWorld account; a limited source's tools must then name a subsidiary_id, and free-form SuiteQL, items and campaigns are off. Then add a netsuite connection: its tools list customers, leads, contacts and transactions, summarize sales by period, read any record, run SuiteQL queries and, on connections that allow changes, create or update customers, leads, prospects, contacts and notes (never delete). For live events, turn on Live events and upload our SuiteScript (GET .../netsuite/script, with the address built in) in NetSuite.
• Blazeo (formerly ApexChat): chat leads. Blazeo has no API; it sends each lead to a webhook URL. On the Data Sources tab choose Blazeo and press Add; with the API, send PUT .../data-sources/{source} with type blazeo and no credentials. The reply holds webhook_url (shown only once: it is stored as a hash), the method (POST, JSON) and the field names. Send them to Blazeo support, who set up the "CRM integration". Webhook on the data source (GET .../data-sources/{source}/blazeo) shows whether leads arrive; POST .../blazeo/test stores a test lead and POST .../blazeo/rotate makes a new URL (the old one stops at once). Then add a blazeo connection: its tools list, read and count leads. Leads are kept for 25 months; deleting the data source deletes them.
• TechShip (Techdinamics): shipments, freight costs, carriers, clients, boxes and manifests. Ask your Techdinamics contact for the portal's API key and secret key (one key set per portal). On the Data Sources tab choose TechShip, pick the portal's region (US, Canada, Europe) or enter its own TechShip address, and paste both keys; with the API, send PUT .../data-sources/{source} with type techship, api_key, secret_key and api_url (us, ca, eu or an https host on techship.io or techship.ca). The keys are tried before they are saved. One portal holds many TechShip clients, so press Accounts (or send allowed, for example {"techship": ["client:ACME"]}) to limit it to one client; a limited data source's reports must then name that client, and manifests (which span clients) are off. Then add a techship connection: its tools list and count shipments, total freight costs by day, service, carrier account or client, read carriers, boxes and manifests, and quote rates (a dry run). With changes allowed on the connection it can also create, update, void and delete shipments and finalize manifests, each after a preview and confirm. TechShip lets one key run 10 requests at once, shared with the customer's own systems, so long date ranges are read one day at a time. Shipments are linked to visitors in Attribution by their order number. TechShip has no webhooks, so there are no live events; deleting the client deletes the saved keys (ask Techdinamics to retire them too).
• Live events (webhooks): Shopify, Meta (Facebook Pages and Instagram), CallRail, WordPress (form submissions with the Metric Sensei plugin 1.3.0+, and WooCommerce) and Google (Business Profile reviews, Merchant Center product status, Google Ads lead forms) and MNTN (verified visits) can push events as they happen. Metric Sensei registers the webhooks with the platform itself when the data source is connected (on by default) and removes them when it is deleted. Live events on the data source (GET|PUT .../data-sources/{source}/live-events) shows the status and switches topics on or off; POST .../live-events/sync checks now (it also runs daily), POST .../live-events/test stores a test event, and GET .../live-events/events lists what arrived (kept 25 months). AI apps read them with each service's *_list_live_events, *_get_live_event and *_live_events_status tools. Google Ads lead forms and MNTN are the manual steps: paste the URL and key shown there into each lead form, and paste MNTN's URL (macros included) once into MNTN › My Account › Creative Tracking › Default Macro-Enabled Visit Tracking. MNTN visitor IPs are never stored, only a one-way hash. Facebook sign-ins need the pages_manage_metadata and leads_retrieval permissions, so sign in again once.
• Salesforce: on the Data Sources tab choose Salesforce › Sign in with Salesforce and pick the org's login (production, sandbox or its My Domain); with the API, POST .../data-sources/{source}/sign-in with type salesforce, login and, for a My Domain, my_domain. One data source is one org, and it sees and changes only what the Salesforce user who signs in can, so sign in as a dedicated integration user (read-only if AI apps should never change records). That user needs the API Enabled permission. First, a Salesforce admin of the org installs Metric Sensei once from the install link shown in the Add data source dialog (salesforce_oauth.install_links in GET /meta; choose Install for Admins Only), and keeps its refresh token policy at valid until revoked. Press Objects (or send allowed, for example {"salesforce": ["object:Lead", "object:Opportunity"]}) to limit it further: queries, searches and record changes then stay inside those objects, including lookups such as Contact.Account.Name, and reports and dashboards are switched off. A salesforce connection describes objects, runs SOQL queries and text searches, reads records, runs reports and dashboards, and summarizes leads, the opportunity pipeline and campaigns; with changes allowed it creates, updates and deletes records (deleted ones go to the Recycle Bin for 15 days), adds or removes campaign members and logs tasks and calls, one record at a time (each asks for confirm=true first).
• RingCentral: on the Data Sources tab choose RingCentral › Sign in with RingCentral; with the API, POST .../data-sources/{source}/sign-in with type ringcentral. Sign in as an admin of the client's RingCentral account: the company call log, call analytics and RingCX need admin rights. One sign-in serves two services. A ringex connection (phone system) lists users, call queues and phone numbers, reads the call log and single calls with their legs, recording details (never the audio), call totals and timelines from RingCentral's Business Analytics, and text messages; with changes allowed it sends a text from the signed-in person's number. A ringcx connection (contact center) lists sub-accounts, dial groups, campaigns, queues and agents, searches leads, shows calls in progress and finished interactions (needs WEM access); with changes allowed it loads leads into a campaign and pauses, readies, resets, cancels, suppresses or deletes leads. Every change asks for confirm=true first. Press Accounts (or send allowed) to limit RingEX to some users or queues ({"ringex": ["extension:62912345008"]}) and RingCX to some sub-accounts, campaigns or queues ({"ringcx": ["campaign:1234"]}). Live events record each finished call company-wide and texts to the person who signed in. Metric Sensei refreshes RingCentral sign-ins every 15 minutes (RingCentral's refresh tokens work once and expire after a week unused), and deleting the data source or the client revokes the sign-in at RingCentral.
• HubSpot: on the Data Sources tab choose HubSpot › Connect HubSpot; with the API, POST .../data-sources/{source}/sign-in with type hubspot. The link installs Metric Sensei in the HubSpot account picked when it is opened (someone who can install apps there approves), and one data source is one HubSpot account. Accounts that can't install apps can paste a private app's access token instead (api_key, starting pat-); live events then aren't available. Press Objects (or send allowed, for example {"hubspot": ["object:contacts", "object:deals", "object:forms"]}) to limit it to object types (custom objects too) and marketing tools (forms, marketing emails, campaigns, lists). A hubspot connection searches and reads records with their links, lists properties, pipelines, owners, forms and their submissions, marketing emails with their stats, campaigns and lists, and summarizes the deal pipeline and new contacts; with changes allowed it creates, updates and archives records (restorable in HubSpot for 90 days), links records, logs notes, tasks and calls, and adds or removes static list members (each asks for confirm=true first). Live events: contacts, companies, deals and tickets created, changed, deleted or merged.
• Google AdSense: on the Data Sources tab add (or edit) a Google data source and tick Google AdSense; with the API, POST .../data-sources/{source}/sign-in with type google and uses including adsense (the sign-in asks for AdSense only when it is ticked). An adsense connection reads earnings reports (by date, page, site, ad unit, country, device and more), a quick overview, saved reports, sites and their approval state, ad units and their code, custom and URL channels, payments, alerts and policy issues, and checks each site's ads.txt for Google's line. Google lets the API create and rename ad units and custom channels only for AdSense for Platforms accounts; archiving an ad unit or deleting a channel asks for confirm=true first. Setup checks say when the account or a site needs attention, ads.txt is missing Google's line, a policy issue limits ads or Google raised an alert (such as a payment hold). Link a website to an AdSense account in its Analytics settings (sources.adsense) to see its earnings next to its page views.
• Google Data Manager: on the Data Sources tab add (or edit) a Google data source and tick Google Data Manager; with the API, uses including datamanager. It sends the client's own data to Google Ads: Customer Match audiences (create, add and remove people) and offline conversions. Emails and phone numbers are normalized and hashed before they leave Metric Sensei and are never stored. Every change asks for confirm=true first and can run as a test (validate_only); Google processes uploads in the background, and the upload status (GET .../datamanager/status or datamanager_get_upload_status) shows how it went and the match-rate range. Set the connection's customer_match_terms to accepted once the client accepted Google's Customer Match terms. Offline conversions for a Google Ads mapping go through Data Manager when the Google sign-in includes it. Deleting the client empties the audiences Metric Sensei created.
• Mailchimp: on the Data Sources tab choose Mailchimp › Connect Mailchimp; with the API, POST .../data-sources/{source}/sign-in with type mailchimp. Whoever opens the link signs in to Mailchimp and allows Metric Sensei; one data source is one Mailchimp account. You can paste an API key instead (Mailchimp › Profile › Extras › API keys; api_key, ending in the data center such as -us21); it is tried before it is saved. Press Audiences (or send allowed, for example {"mailchimp": ["audience:abc123def4"]}) to limit it to some audiences. A mailchimp connection lists audiences, campaigns, automations, segments, tags, ecommerce stores and orders; reports campaign results in the same rows as other email platforms (recipients, delivered, opens, clicks, rates, unsubscribes, bounces, spam complaints, orders, revenue), daily audience activity, monthly growth and clicks per link; and searches and reads subscribers. With changes allowed it adds or updates subscribers, adds or removes tags, unsubscribes or archives a subscriber, creates draft campaigns and sends tests (each asks for confirm=true first; it never sends or schedules a real campaign and never deletes permanently). Live events (registered on each allowed audience): sign-ups, unsubscribes, profile and email changes, cleaned addresses and, if you choose, campaign sends. With Attribution on, subscribers who click a Mailchimp email are matched to their visits. Mailchimp sign-ins don't expire; to cut Metric Sensei off, remove it under Mailchimp › Profile › Integrations (deleting the client only deletes our copy, since Mailchimp has no way to revoke one).
• Gorgias (customer service helpdesk): on the Data Sources tab choose Gorgias › Connect Gorgias and enter the account name (the acme in acme.gorgias.com); with the API, POST .../data-sources/{source}/sign-in with type gorgias and domain. An admin of the Gorgias account opens the link and approves our app; one data source is one Gorgias account. Accounts that can't install apps can paste a user's email and REST API key instead (Gorgias › Settings › REST API; PUT .../data-sources/{source} with type gorgias, domain, email and api_key); the key has that user's permissions, and live events need an admin's key. Press Areas (or send allowed, for example {"gorgias": ["area:customers", "area:statistics"]}) to limit it to tickets, customers, satisfaction surveys, statistics or voice calls. A gorgias connection lists and reads tickets with their messages, views, customers with the orders of stores linked in Gorgias, satisfaction surveys (CSAT), Gorgias's support statistics (response and resolution times, volume per channel, tag and agent, revenue), voice calls, users, teams, tags and macros; with changes allowed it adds internal notes, replies to customers on the ticket's channel, changes a ticket's status, priority or assignee, adds or removes tags and updates a customer (each asks for confirm=true first; nothing is deleted). Live events (new tickets, new messages, tickets opened or closed, assignments) arrive through HTTP integrations we add in Gorgias named "Metric Sensei live events". With Attribution on, tickets and customers are linked to website visitors by email, phone and order. Gorgias has no way to cancel our sign-in from outside, so after deleting the data source or the client remove the Metric Sensei app in Gorgias too.
• Klaviyo: on the Data Sources tab choose Klaviyo › Connect Klaviyo; with the API, POST .../data-sources/{source}/sign-in with type klaviyo. The link installs Metric Sensei in the Klaviyo account an owner, admin or manager approves, and one data source is one Klaviyo account. You can paste a private API key instead (api_key, starting pk_; Klaviyo › Settings › API keys; a read-only key can't make changes). Press Kinds of data (or send allowed, for example {"klaviyo": ["data:reports", "data:campaigns"]}) to limit it to reports, campaigns, flows, lists and segments, profiles, events, sign-up forms or templates: without profiles and events it never reads anyone's personal data. A klaviyo connection reports campaign, flow and sign-up form results (the same rows as other email platforms: recipients, opens, clicks, unsubscribes, bounces, orders, revenue), email activity over time and metric totals, and lists campaigns, flows, lists, segments, profiles, events, forms, templates and tags. Reports are kept for 30 minutes (6 hours for past days) because Klaviyo allows few report calls a day. With changes allowed it creates or updates profiles, subscribes (only people who agreed) and unsubscribes, adds or removes list members, makes lists, tags campaigns, flows, lists and segments, records custom events, and creates draft campaigns, which a person sends from Klaviyo (each asks for confirm=true first). Live events (clicks, subscribes and unsubscribes, bounces, opens, SMS): set up automatically when the Klaviyo account may use webhooks (Klaviyo allows that for its app partners and Advanced KDP accounts); otherwise Live events shows an address and body to paste into a flow's Webhook action. Emails from live events are kept only as a one-way hash. Setup checks say when permissions, the Placed Order metric (store revenue) or webhooks are missing. Deleting the data source or the client removes our webhook, and deleting the client revokes the sign-in when no other client uses the same Klaviyo account.

Then add a connection that uses it: PUT /clients/{client}/connections/{service}/{name} with data_source. Before adding it, list_source_setting_choices lists a setting's choices (for example the GA4 properties) with the data source's sign-in, just like the admin page's Add connection. After, list_setting_choices does the same for a saved connection, and save_connection changes its settings. Signing in again (or new credentials) on a data source updates every connection that uses it. PageSpeed Insights (pagespeed) tests public pages, so its connections need no data source.

Limiting a data source to some accounts. A Google sign-in often sees many accounts. For each service you can choose which ones a data source may reach: GA4 accounts and properties, Google Ads accounts (a manager includes the accounts under it), Tag Manager accounts and containers, Search Console sites, Business Profile accounts and locations, Merchant Center accounts and AdSense accounts. A Facebook sign-in can be limited per service to business portfolios (which include everything they own or manage for clients), ad accounts, Pages and Instagram accounts, for example {"allowed": {"meta_ads": ["business:123"], "instagram": ["ig_account:178414..."]}}. list_data_source_scope_choices (GET /clients/{client}/data-sources/{source}/scope-options/{service}) lists what the sign-in can see as a tree, with the current choice; save_data_source with allowed saves it, for example {"allowed": {"ga4": ["account:123", "property:456"], "ads": ["customer:1234567890"]}}. Picking a parent includes everything under it, also things added later. A service you leave out may reach everything. Tool calls through the API/MCP Gateway outside the choice are refused, lists only show what is allowed, and connection defaults must be inside it. Shopify data sources are always exactly one store.

Health alerts. Once a day we check that each data source can still sign in to Google or Facebook, or read its Shopify store (nothing is changed there). list_alerts (GET /alerts) lists the ones that stopped working, for example a Google or Facebook sign-in that was revoked or expired, or a Shopify app that was uninstalled, in every client you manage. check_data_sources (POST /clients/{client}/data-sources/check) checks a client's sources right away, and each data source shows its last result in health. To fix one, call start_data_source_sign_in for the same data source and sign in again: the alert clears and every connection using it works again.

Keeping it safe

• Treat a token like a password. Don't put it in code or chat; use an environment variable or a secret store.
• Use read-only tokens unless you need changes, and the shortest expiry that works.
• Make one token per tool or agent so you can revoke one without the others. Last used in the admin page shows which are active.
• If a token leaks, revoke it in the admin page right away.

Me

Your own access, API/MCP Gateway keys and API tokens (list only), and connected apps. Everyone can use these.

Agencies

An agency owns, manages and pays for a set of clients. A customer with one client has a solo agency of its own.

Clients

Clients are the companies or sites whose data the API/MCP Gateway serves.

Data sources

A client's accounts (Google, Facebook, Microsoft, Salesforce and RingCentral sign-ins, Shopify stores, HubSpot, Mailchimp, Gorgias and Klaviyo accounts, CallRail, Bing Webmaster, Supermetrics, MNTN and TechShip keys) with their credentials. A client can have many of each; services use them through connections.

Connections

How each service (Google Analytics 4, Tag Manager, Search Console, Business Profile, Merchant Center, Ads, AdSense, PageSpeed Insights, Shopify, Meta Ads, Facebook Pages, Instagram, Meta Business, WordPress, CallRail, Microsoft Advertising, Bing Webmaster Tools, Supermetrics, Salesforce, MNTN, RingEX, RingCX, HubSpot, TechShip, Mailchimp, Gorgias, Klaviyo) uses one of the client's data sources, with its own settings.

Gateway keys

Keys that let a person use a client's connections through the API/MCP Gateway. Not the same as API tokens. List only; keys are created and revoked in the admin page.

Client users

The people in a client and which connections each one can use.

Connected apps

Apps (for example AI assistants) signed in to the API/MCP Gateway for a client.

Identity

A client's company sign-in (SSO), email domains and social sign-in choices.

Tracking

Tracked sites (websites, iOS and Android apps, APIs) shared by services, websites' tags and snippets, attribution settings and the dashboard. The /attribution/sites endpoints are the websites with Attribution on.

Privacy requests

A client's website visitor asks to see or delete their data. Log the request, check who is asking, search every service, then export or delete; the client answers the visitor.

Billing

Usage, invoices (one per agency per month, broken down by client), payments, balance and saved cards.

Pricing

Monthly base fee per service per client, free usage included, and prices above it.

Activity

Who changed what, and when, in a client or agency (admin page, this API and API/MCP Gateway write tools).

Usage

API/MCP Gateway tool calls per day, per service and per client (successful calls are billed, failed ones are not), and the numbers on a client's and an agency's Home.

SEO

SEO (rank tracking, keyword research, site audits, backlinks, competitors, local grids, content briefs, AI visibility, alerts, reports, link prospects, log analysis) for clients with SEO on. One route runs every SEO operation; the operations and their arguments are the same as the API/MCP Gateway's seo_* tools.

Analytics

Website analytics for a client with Analytics on: traffic, channels, pages, goals, revenue, funnels, cohorts, heatmaps, recordings, A/B tests and the comparison with GA4. Everything the Analytics screen shows, run as you; the Analytics service checks your role in the client on every call. Most take a date range: `range` (today, yesterday, last_7_days, last_28_days, last_30_days, last_90_days, this_month, last_month, this_year, last_12_months or custom with `start` and `end`), in the website's own time zone. Settings (goals, funnels, linked sources) are under Tracking.