Tracebird API & MCP

Current workspace and credential

Returns the Tracebird workspace this credential belongs to (name, currency, timezone, plan), the acting user and the granted scopes. Call this first to confirm the connection works.

MCP tool: get_workspace

Workspace profile and settings

Returns the workspace profile Settings → Workspace edits: name, website, logo, main currency, workspace timezone, revenue source preference and who owns it. Use get_workspace for the quick connection check including plan.

MCP tool: get_workspace_settings

Update the workspace profile

Changes the workspace name, website, main currency, workspace timezone or revenue source preference (admins only; send only the fields to change). Currency and timezone change how every report and dashboard total is shown, so confirm with the user before calling.

MCP tool: update_workspace

Workspaces the user belongs to

Lists every workspace the credential's user is a member of, with their role. Informational only: a credential always acts on the one workspace it was issued for.

MCP tool: list_workspaces

The user's settings

Returns the acting user's Settings → General preferences in this workspace: reporting timezone (the clock behind every day boundary), defaults, display and notification preferences.

MCP tool: get_user_settings

Update the user's settings

Saves Settings → General preferences for the acting user (send only the fields to change). Changing timezone moves the user's reporting day boundaries for all their reports, so confirm with the user before calling.

MCP tool: update_user_settings

List notifications

Lists the workspace's in-app notifications (integration problems, automation alerts, system notices), newest first, excluding dismissed ones. Filter by unread or by category.

MCP tool: list_notifications

Unread notification count

Returns the number of unread notifications and the five most recent ones. Use it to check whether anything needs attention.

MCP tool: get_notification_summary

Mark a notification read

Marks one notification as read. Safe to repeat.

MCP tool: mark_notification_read

Mark all notifications read

Marks every unread notification in the workspace as read.

MCP tool: mark_all_notifications_read

Dismiss a notification

Dismisses a notification so it no longer appears in the list (it is also marked read).

MCP tool: dismiss_notification

List workspace logs

Lists Settings → Logs, newest first: integration syncs, automation runs, actions by team members, API and MCP changes, and operational events. Filter by category, outcome (status), time window or search text.

MCP tool: list_logs

Billing status and plan usage

Returns the workspace's plan, billing status (demo, trialing, active, past_due, canceled), trial end, seat and ad account limits and trailing 30-day ad spend against the plan's allowance. Read-only: checkout, plan changes and the payment portal are only available in the app. Works on lapsed workspaces so you can see why access is limited.

MCP tool: get_billing

List team members and seat usage

Returns { members, seats }: the workspace's members with their role (admin, manager or viewer), who owns the workspace, and seat usage against the plan's limit (pending invitations count against it). Admins only.

MCP tool: list_team_members

Change a member's role

Team changes affect who can access the workspace: confirm with the user before calling. Sets a member's role to admin, manager or viewer (admins only). Promoting to admin needs a plan with team access. You cannot demote yourself or the workspace owner.

MCP tool: update_team_member_role

Remove a team member

Team changes affect who can access the workspace: confirm with the user before calling. Removes a member from the workspace immediately (admins only). The owner and yourself cannot be removed.

MCP tool: remove_team_member

List team invitations

Lists the latest 100 invitations (pending, accepted or revoked), newest first. Admins only.

MCP tool: list_team_invitations

Invite a team member

Team changes affect who can access the workspace: confirm with the user before calling. Emails an invitation to join the workspace as admin, manager or viewer (admins only, needs a plan with team access). The invitation is valid for seven days and counts against the seat limit; the same address can only be emailed 3 times per hour.

MCP tool: invite_team_member

Resend a team invitation

Team changes affect who can access the workspace: confirm with the user before calling. Emails a pending invitation again with a fresh link and a new seven-day expiry; the previous link stops working (admins only).

MCP tool: resend_team_invitation

Revoke a team invitation

Team changes affect who can access the workspace: confirm with the user before calling. Revokes a pending invitation so its link stops working (admins only).

MCP tool: revoke_team_invitation

List outbound webhooks

Lists the workspace's outbound webhooks (Settings → Integrations → Webhooks), including revoked ones, with the event types each receives and whether it is enabled. Signing secrets are never returned after creation; non-admins see endpoint URLs without query strings.

MCP tool: list_webhooks

List webhook event types

The event types an outbound webhook can subscribe to. Payload schemas are in the OpenAPI spec's webhooks section and on /docs/api#webhooks. Each delivery is a POST with a JSON body { id, type, created_at, workspace_id, data } and the headers Tracebird-Event, Tracebird-Delivery (unique id; use it or the event id for idempotency) and Tracebird-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the signing secret>.

MCP tool: list_webhook_event_types

Create an outbound webhook

Creates an outbound webhook to an HTTPS endpoint (admins only, max 25 active) that receives the chosen events (default: all). The response contains the signing secret exactly once: show it to the user and never store or repeat it. Confirm the endpoint with the user first. Each delivery is a POST with a JSON body { id, type, created_at, workspace_id, data } and the headers Tracebird-Event, Tracebird-Delivery (unique id; use it or the event id for idempotency) and Tracebird-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" keyed with the signing secret>. Failed deliveries (non-2xx or no answer in 10 s) are retried 5 more times over about 24 hours.

MCP tool: create_webhook

Update an outbound webhook

Changes a webhook's name, endpoint URL or event types, or disables / re-enables it (admins only). Re-enabling a webhook that was disabled after repeated failed deliveries clears its failure count; send a test first to check the endpoint. Only the fields you pass change.

MCP tool: update_webhook

Send a test event

Sends one signed `webhook.test` event to the webhook right now (also when it is disabled) and returns whether the endpoint answered 2xx. Test events are not retried and never count toward auto-disable.

MCP tool: test_webhook

List a webhook's deliveries

The delivery log, newest first (kept 30 days): event type and id, status (pending = will retry at next_attempt_at, delivered, failed), attempts, the last HTTP status and error.

MCP tool: list_webhook_deliveries

Revoke an outbound webhook

Revokes a webhook so it stops receiving events (admins only). This cannot be undone; confirm with the user before calling.

MCP tool: revoke_webhook

Security audit log

Returns the newest security and workspace audit events (who did what, when): API key and webhook changes, member actions, and changes made through the API or MCP. Newest first, one page of up to 100.

MCP tool: list_audit_log

List API keys

Lists the workspace's API keys (metadata only: name, key prefix, scopes, last use, expiry, revocation). Secrets are never returned, and keys can only be created or revoked in the app.

MCP tool: list_api_keys

List connected apps

Lists the OAuth apps connected to the workspace, such as AI assistants using MCP (metadata only). Admins see everyone's connections, other members their own. Connections can only be revoked in the app.

MCP tool: list_connected_apps

List connected ad accounts

Lists the ad accounts connected to the workspace across Facebook and Google Ads, with currency, timezone and whether the account is enabled in Tracebird. Use it first to learn account ids (for the account_id filter) and the currency that spend and budget amounts are reported in.

MCP tool: list_ad_accounts

List campaigns

Lists campaigns synced from Facebook and Google Ads: name, status, objective, budget, bid strategy and account. Use it to find campaign ids or to monitor structure and status; use get_insights for performance numbers. Results are ordered by updated_at then id, so passing the newest `updated_at` you saw as `updated_since` and following `next_cursor` gives a stable incremental sync. Money fields are numbers in major units of the account `currency`; times are ISO 8601 UTC.

MCP tool: list_campaigns

Get a campaign

Returns one campaign by its platform id (name, status, objective, budget, bid strategy, account and currency). Use list_campaigns to discover ids.

MCP tool: get_campaign

List ad sets

Lists ad sets (Google Ads ad groups): name, status, budget, bid strategy, schedule and parent campaign. Filter by campaign_id to see one campaign's ad sets. Results are ordered by updated_at then id, so passing the newest `updated_at` you saw as `updated_since` and following `next_cursor` gives a stable incremental sync. Money fields are numbers in major units of the account `currency`; times are ISO 8601 UTC.

MCP tool: list_ad_sets

Get an ad set

Returns one ad set by its platform id (status, budget, bid strategy, schedule, parent campaign). Use list_ad_sets to discover ids.

MCP tool: get_ad_set

List ads

Lists ads with status, parent ad set and campaign, and creative details (format, preview link, primary text, headline, call to action, destination URL). Filter by ad_set_id or campaign_id. Results are ordered by updated_at then id, so passing the newest `updated_at` you saw as `updated_since` and following `next_cursor` gives a stable incremental sync. Money fields are numbers in major units of the account `currency`; times are ISO 8601 UTC.

MCP tool: list_ads

Get an ad

Returns one ad by its platform id with status, parent ids and creative details. Use list_ads to discover ids.

MCP tool: get_ad

Duplicate campaigns, ad sets or ads

LIVE CHANGE on the real ad accounts. Confirm the exact assets and change with the user before calling. Up to 50 ids per call. Same rules as the Ads Manager: if an active automation rule has priority the change is refused (HTTP 409); every row reports its own result in "results". Creates copies on the ad platform (paused by default), as the Duplicate action in the Ads Manager does.

MCP tool: duplicate_ads

Delete campaigns, ad sets or ads

LIVE CHANGE on the real ad accounts. Confirm the exact assets and change with the user before calling. Up to 50 ids per call. Same rules as the Ads Manager: if an active automation rule has priority the change is refused (HTTP 409); every row reports its own result in "results". DESTRUCTIVE: deletes the assets on the ad platform and cannot be undone. Prefer pausing (update_campaign / update_ad_set / update_ad) unless the user explicitly asks to delete.

MCP tool: delete_ads

Add Tracebird tracking parameters to ads

LIVE CHANGE on the real ad accounts. Confirm the exact assets and change with the user before calling. Up to 50 ids per call. Same rules as the Ads Manager: if an active automation rule has priority the change is refused (HTTP 409); every row reports its own result in "results". Copies each ad's creative with merged URL tracking parameters so CRM conversions can be matched to the ad (the "Add tracking to ads" action). Ads that already have tracking are skipped.

MCP tool: add_ad_tracking

Change the destination URL of ads

LIVE CHANGE on the real ad accounts. Confirm the exact assets and change with the user before calling. Up to 50 ids per call. Same rules as the Ads Manager: if an active automation rule has priority the change is refused (HTTP 409); every row reports its own result in "results". Points the ads at a new destination URL (and optionally display link) by replacing their creative, as the Change destination action does. This changes where live traffic lands.

MCP tool: change_ad_destination

Ad writes that need review

Lists manual ad writes whose outcome is uncertain (the platform may or may not have applied them; the assets stay locked) and known partial results that need reconciling. Use before retrying a failed or timed-out write.

MCP tool: list_asset_write_intents

Acknowledge a completed ad write

Releases a completed write intent after its result was received. Uncertain writes stay locked; they must be checked in the ad platform first. Confirm with the user.

MCP tool: acknowledge_asset_write_intent

Re-read Meta for a known partial write

Reads the current Meta state of the ads touched by a known partial write (live call, changes nothing) and returns an `inspectionVersion` to pass to reconcile_partial_write_intent.

MCP tool: inspect_partial_write_intent

Acknowledge a known partial write

Marks a known partial write as reviewed after inspect_partial_write_intent. Re-reads Meta and refuses if the state changed since the inspection. Confirm with the user that they reviewed the latest Meta state; any new creative change needs a new explicit action.

MCP tool: reconcile_partial_write_intent

Pause, resume, rename or change the budget of a campaign

LIVE CHANGE: this takes effect on the real ad account immediately and can change delivery and spend. Confirm the exact change with the user before calling. It follows the same rules as the Tracebird Ads Manager: if an active automation rule has priority, the change is refused with an explanation (HTTP 409) instead of being forced. Send exactly one of status (ACTIVE | PAUSED), name or daily_budget per request. daily_budget only works on campaigns with their own budget (campaign budget / CBO); for ad set budgets (ABO) update each ad set instead.

MCP tool: update_campaign

Pause, resume, rename or change the budget of an ad set

LIVE CHANGE: this takes effect on the real ad account immediately and can change delivery and spend. Confirm the exact change with the user before calling. It follows the same rules as the Tracebird Ads Manager: if an active automation rule has priority, the change is refused with an explanation (HTTP 409) instead of being forced. Send exactly one of status (ACTIVE | PAUSED), name or daily_budget per request. daily_budget is refused when the ad set uses its campaign's budget (CBO); update the campaign instead.

MCP tool: update_ad_set

Pause, resume or rename an ad

LIVE CHANGE: this takes effect on the real ad account immediately and can change delivery and spend. Confirm the exact change with the user before calling. It follows the same rules as the Tracebird Ads Manager: if an active automation rule has priority, the change is refused with an explanation (HTTP 409) instead of being forced. Send exactly one of status (ACTIVE | PAUSED), name per request.

MCP tool: update_ad

Ad performance by day or total

Returns advertising performance for a date range at account, campaign, ad set or ad level: spend, impressions, clicks, CTR, CPC, CPM, platform-reported purchases and purchase value, platform ROAS, plus attributed leads and revenue from the connected attribution source (HYROS) when present. Use time_increment=day for a daily time series (one row per entity per day) or total for one row per entity over the whole range. The range is limited to 93 days; request several windows for longer histories. Days are the calendar days the ad platform reports for each ad account (the account's own timezone), so they can differ slightly from the workspace reporting timezone. Money is a number in major units of the row's `currency` (the ad account currency); rows are never mixed across currencies. Reach is only returned at ad level with time_increment=day because reach is not additive across days or entities. For revenue that comes from CRM/Stripe sales (not ad-platform reported), use get_revenue or get_performance_summary.

MCP tool: get_insights

Workspace KPI totals for a date range

Returns the same workspace totals as the Tracebird dashboard for a date range: ad spend, impressions, clicks, platform purchases and ROAS, attributed leads and revenue, CRM funnel counts (leads, appointments, shows, sales) with CRM revenue, Stripe net revenue, and front-end / back-end / blended revenue with the dashboard's ROAS and CAC (revenue.roas, revenue.cac: revenue or customers against revenue.ad_spend; null when a stage has no revenue source or spend is in mixed currencies; lower bounds while revenue.maturing is true). Use it for a quick overview of how the business is doing; use get_insights for per-campaign or per-day breakdowns and get_revenue for the revenue split alone. Money is converted to the workspace main currency (`currency`) at daily FX rates where a rate exists. Days follow the workspace reporting timezone (`timezone`). The range is limited to 93 days; on a trial only the last 30 days are available.

MCP tool: get_performance_summary

Front-end, back-end and blended revenue

Returns workspace revenue split into front-end (the initial offer) and back-end (higher-ticket follow-up) sales, plus blended (their sum), with distinct buyers and deals, for a date range. Each sale is counted once by the revenue source configured under Settings > Revenue. basis=sale (default) uses the day each sale happened; basis=acquisition attributes revenue to the day the customer was acquired (later back-end sales still count, so recent ranges are lower bounds while `maturing` is true). Amounts are numbers in major units of the workspace main currency (`currency`) where FX rates exist; an amount in a currency without a rate is listed as its own entry in `by_currency`. Days follow the workspace reporting timezone. Range limit: 93 days.

MCP tool: get_revenue

Performance broken down by placement, age, gender, country...

Returns ad performance for a date range split by one dimension (placement, device, age, gender, age_gender, country, page or instagram), workspace-wide or scoped to one ad account or one campaign / ad set / ad. Same data and rules as the Insights breakdowns in the app: when the scope mixes currencies or ad accounts cannot be verified, `state` is `rejected` with a `reason` instead of rows. Money is in the `currency` of the scope.

MCP tool: get_insight_breakdowns

Front-end / back-end revenue per campaign, ad set or ad

Returns front-end, back-end and blended revenue (and optionally LTV over 30, 90 or 365 days) for specific campaigns, ad sets or ads, the numbers behind the FE/BE columns of the Ads Manager. Money is in the workspace main currency. Range limit: 93 days.

MCP tool: get_funnel_asset_metrics

Daily performance of one creative with workspace benchmarks

Returns one ad's daily series (spend, impressions, reach, clicks, leads, purchases, revenue, CTR, frequency) for a date range plus workspace median benchmarks (hook rate, CTR, CPL, CPM, ROAS), as in the creative detail view. Range limit: 93 days.

MCP tool: get_creative_detail

Placement, age, gender and device breakdowns of one creative

Returns placement, age, gender and device breakdowns for one ad over a date range. Meta ads are read live from Meta with the workspace connection (not stored); `source` says where the data came from and `error` explains when it is unavailable. Range limit: 93 days.

MCP tool: get_creative_breakdowns

Preview link of an ad

Returns how an ad looks: for Meta ads a preview iframe URL (`type` meta_preview_url), for Google Ads a native preview model (`type` google_ad). `type` is null when no preview is available (sample ads, disconnected account).

MCP tool: get_ad_preview

Cards, columns and chart options the dashboard accepts

Lists the metric card keys, campaign table columns, chart palettes and limits that get_dashboard_preferences / update_dashboard_preferences accept, so a valid layout can be built. Also lists the Ads Manager table view defaults.

MCP tool: list_dashboard_options

The dashboard layout of the key owner

Returns the dashboard layout saved for the API key's owner in this workspace: main and secondary metric cards, chart series, campaign columns and chart styling. `saved` is false (and the app defaults are returned) until a layout was saved. Use list_dashboard_options for valid keys.

MCP tool: get_dashboard_preferences

Change the dashboard layout of the key owner

Merges the given fields into the key owner's saved dashboard layout (only your own layout; other members are unaffected) and returns the normalized result; unknown card keys are dropped. Example: {"preferences":{"cards":["spend","funnel_blended_revenue"],"chartSeries":["spend","revenue"],"chartType":"bar"}}. Send expected_updated_at from get_dashboard_preferences to fail with 409 if the layout changed meanwhile.

MCP tool: update_dashboard_preferences

Daily spend and revenue series

Returns the dashboard chart series: one point per day (zero-filled) with ad spend and revenue in the workspace main currency, in the key owner's reporting timezone, optionally for one ad account. Range limit: 93 days.

MCP tool: get_dashboard_trend

Stripe revenue for a period and the one before

Returns the dashboard's Stripe revenue view for the date range and the equal-length previous period (for the period-over-period comparison). `source` says whether Stripe data was available. Range limit: 93 days.

MCP tool: get_dashboard_revenue

Customers grouped by source, campaign, ad or month

Returns customer counts and revenue grouped by acquisition source, campaign, ad or first-seen month, with the same filters as the Customers page.

MCP tool: list_customer_groups

Saved Ads Manager views

Lists the workspace's saved Ads Manager filter views (up to 100, newest first).

MCP tool: list_manager_views

Save an Ads Manager view

Saves a named set of Ads Manager filters and hidden columns, shared with the workspace. Example: {"name":"Active spenders","filters":[{"field":"status","value":"ACTIVE"}],"hidden_columns":["reach"]}.

MCP tool: create_manager_view

Change a saved Ads Manager view

Renames a saved view or replaces its filters / hidden columns; omitted fields keep their value.

MCP tool: update_manager_view

Delete a saved Ads Manager view

Permanently deletes a saved view for the whole workspace. Confirm with the user.

MCP tool: delete_manager_view

Ads Manager table views of the key owner

Returns the key owner's saved Ads Manager table views (column set and order, widths, sort, pinned columns) and which is selected. Defaults are returned until saved.

MCP tool: get_table_views

Save the Ads Manager table views of the key owner

Replaces the key owner's table views (last write wins; send the complete list from get_table_views with your changes). Example: {"preferences":{"selectedId":"mine","views":[{"id":"mine","name":"Mine","favorite":true,"columns":["delivery","spend","funnel_blended_roas"],"widths":{},"pinned":[],"sort":{"key":"spend","dir":"desc"}}]}}. At most 30 views.

MCP tool: update_table_views

The workspace's public dashboard embed link

Returns the workspace's embed link (public id, path /embed/<public_id>, display config, view counts, whether a password is set) or null when none exists. Passwords are never returned.

MCP tool: get_dashboard_embed

Create or rotate the dashboard embed link

Creates the workspace's public embed link, or ROTATES it when one exists (the previous URL stops working; the display config and password are kept). Anyone with the link can see the configured numbers: confirm with the user, especially before rotating.

MCP tool: create_dashboard_embed

Change what the embed shows

Merges the given display settings into the embed config (cards, timeframe, asset level, accounts, filters, theme, widget template...). Display only; it cannot widen data access. Changes what viewers of the public link see: confirm with the user.

MCP tool: update_dashboard_embed_config

Revoke the dashboard embed link

Turns the public embed link off immediately; every page using it stops working. Confirm with the user. create_dashboard_embed makes a new one.

MCP tool: revoke_dashboard_embed

Set the embed password

Sets or changes the password viewers must enter to open the embed (8-128 characters recommended by the app limits); signs out current viewers. The password is never returned or readable afterwards. Confirm with the user.

MCP tool: set_dashboard_embed_password

Remove the embed password

Removes the embed password so anyone with the link can open it. Confirm with the user.

MCP tool: clear_dashboard_embed_password

Ad accounts an embed can be scoped to

Lists the ad accounts (busiest first) that can be put in the embed config's `accounts`.

MCP tool: list_embed_account_options

Preview what the embed shows

Renders the embed with live workspace data for a draft config (or the saved config when omitted) without saving anything.

MCP tool: preview_dashboard_embed

Preview the phone widget text

Renders the phone widget text of the embed for a draft config (or the saved config when omitted) without saving anything.

MCP tool: preview_dashboard_embed_widget

KPI keys a report can include

Lists the KPI keys accepted in a report's config.metrics, the report templates and the row limit, so valid report definitions can be built. crm_* keys only show data once the workspace records CRM conversions.

MCP tool: list_report_metrics

Saved reports

Lists the workspace's saved report definitions (newest first, up to 500). Archived reports are hidden unless status=archived or all.

MCP tool: list_reports

One saved report

Returns a saved report definition (name, template, KPI metrics, rows, saved date range).

MCP tool: get_report

Save a new report

Saves a reusable report definition. Use list_report_metrics for valid KPI keys. Example: {"name":"Weekly buyer review","template":"efficiency","config":{"metrics":["spend","revenue","roas"],"rows":10,"comparison":"previous_period"}}.

MCP tool: create_report

Change a saved report

Changes a saved report's name, description, template or definition; omitted fields keep their value. `config` replaces the whole definition (send the complete config).

MCP tool: update_report

Duplicate a saved report

Saves a copy of a report named "<name> copy" and returns it.

MCP tool: duplicate_report

Archive a saved report

Archives a report (hidden from the default list; its schedules stay saved). Confirm with the user.

MCP tool: archive_report

Report email schedules

Lists the workspace's saved report delivery schedules (recipients, cadence, format, enabled), as on the Reports page.

MCP tool: list_report_schedules

Schedule a report

Saves a delivery schedule (recipients, cadence, format) for a saved report, like the Reports page's saved schedule preferences. Confirm the recipients and cadence with the user.

MCP tool: create_report_schedule

Change a report schedule

Changes recipients, cadence, format, timezone or enabled; omitted fields keep their value. Confirm recipient changes with the user.

MCP tool: update_report_schedule

Saved report views

Lists saved views (named page settings per route, private or shared) used by the reports pages.

MCP tool: list_report_views

Save a report view

Saves named page settings for a route. Example: {"name":"Last 30 days","route":"/dashboard/insights/reports","config":{"range":"last_30_days"},"visibility":"shared"}.

MCP tool: create_report_view

Change a saved report view

Changes a saved view; omitted fields keep their value.

MCP tool: update_report_view

Meta attribution window report for ad sets

Runs the Attribution report for ad sets of one Meta ad account over a date range (live Meta read): mode=configured uses the account's configured window, mode=compare compares one extra attribution window. Meta only; Google Ads is not included. Purchase values are in the workspace main currency.

MCP tool: get_attribution_report

List automation rules

Lists the workspace's automation rules (up to 100): name, ON/OFF status, the action they take, asset types, schedule type, folder, appearance and when they last and next run. Use get_automation_rule for a rule's full configuration and list_automation_runs for what rules did.

MCP tool: list_automation_rules

Get the automation rule config structure

Describes the `config` document for create/update/preview_automation_rule: rule, filter and schedule fields, the formula grammar, every metric key with its unit and time windows, the action types and their params, plus complete example configs. Call this before writing a rule.

MCP tool: get_automation_rule_schema

Get an automation rule

Returns one automation rule with its summary and full configuration (filter formula, actions and schedule). Use list_automation_rules to find ids and get_automation_rule_schema to understand the config.

MCP tool: get_automation_rule

List automation run history

Lists recent automation rule executions, newest first: which rule ran, when, whether it succeeded, how many assets it processed, matched and changed, whether it was a dry run, and up to 10 per-asset details. History is kept for 180 days. Times are ISO 8601 UTC.

MCP tool: list_automation_runs

Get the automation run history policy

Returns how long automation run history is kept (retention_days) and how many per-asset details are stored for each run (detail_limit_per_run).

MCP tool: get_automation_history_policy

List automation rule folders

Lists the folders that group automation rules, with how many rules (and how many are ON) each holds. Rules outside any folder are at the root (folder_id null).

MCP tool: list_automation_folders

List pending automation priority items

Lists assets where an automation action is queued or its provider outcome is uncertain (state waiting, uncertain or resolved). While an item is pending, manual edits to that asset are blocked. Uncertain items need reconcile_automation_priority after the user confirms in Ads Manager.

MCP tool: list_automation_priority

Create an automation rule

Creates a rule from a config document (see get_automation_rule_schema; preview it first with preview_automation_rule). It is saved OFF unless status is ON, and only touches ads live when its write_back_mode is approved. Changes live automation; confirm with the user before calling. Turning it ON is refused with 409 if it opposes another enabled rule on the same assets.

MCP tool: create_automation_rule

Update an automation rule

Changes any of name, config (the whole document replaces the old one; fetch it with get_automation_rule, edit, send it back), folder_id ("root" moves it out of its folder), status and icon/color/emoji. Fields you omit stay as they are. Changes live automation; confirm with the user before calling. A rule that is ON keeps running with the new config; saving is refused with 409 if it would oppose another enabled rule.

MCP tool: update_automation_rule

Delete an automation rule

Permanently deletes a rule together with its run history. To keep the history, turn it OFF instead. Changes live automation; confirm with the user before calling.

MCP tool: delete_automation_rule

Duplicate an automation rule

Copies a rule (same folder and appearance) as "<name> Copy", always saved OFF. Returns the new rule.

MCP tool: duplicate_automation_rule

Turn an automation rule on or off

LIVE CHANGE: turning a rule ON lets it start pausing, scaling or editing real ads on its schedule; turning it OFF stops it. Confirm with the user before calling. Same behavior as the toggle in Tracebird: a rule cannot be turned ON while it has opposing actions with another enabled rule on overlapping assets (HTTP 409 with the conflicting rule named in the message), and workspaces without automation access are refused. Use update_automation_rule to change the rule itself.

MCP tool: set_automation_rule_status

Preview an automation rule without saving it

Evaluates a draft config against the workspace's synced assets and reports which match and what the actions would change (up to 100 assets), without saving the rule or changing anything. Check `issues` and `warnings` before create_automation_rule. A POST so the config travels in the body; it needs write scope but has no side effects.

MCP tool: preview_automation_rule

Run an automation rule now

Evaluates a rule that is ON immediately, like "Run now" in Tracebird, and records the run in the history (an OFF rule must be turned ON first with set_automation_rule_status). Changes live automation; confirm with the user before calling. If the rule's write_back_mode is approved it pauses, enables, renames or re-budgets real ads right away; otherwise it only records what it would do. Preview with preview_automation_rule first.

MCP tool: run_automation_rule

Move automation rules to a folder

Moves up to 100 rules into a folder, or out of any folder with folder_id "root". All rule ids must exist, otherwise nothing moves (404).

MCP tool: move_automation_rules

Create an automation folder

Creates a folder for grouping rules (name up to 80 characters, unique in the workspace, up to 500 folders). Returns the folder; use move_automation_rules or the folder_id of create_automation_rule to fill it.

MCP tool: create_automation_folder

Rename an automation folder

Renames a folder (unique name, up to 80 characters). Its rules stay in it.

MCP tool: rename_automation_folder

Delete an automation folder

Deletes a folder. The rules inside are not deleted: they move to the root (no folder) and keep running. Returns how many rules were moved.

MCP tool: delete_automation_folder

Reconcile an uncertain automation priority item

Admin only. Clears an item whose provider outcome was uncertain, after a fresh sync, so automation can be re-evaluated (the old request is never replayed). Only call it after the user confirmed in Ads Manager that the earlier request finished, and set confirm_provider_settled to true. Changes live automation; confirm with the user before calling.

MCP tool: reconcile_automation_priority

List split tests

Lists the workspace's landing-page split tests (up to 100, newest first): status (draft, running, paused, completed), primary metric, variants and their traffic weights, the public split link, visitor counts and the current leader with its probability of beating the control. Use get_split_test_report for full results.

MCP tool: list_split_tests

Get a split test report

Returns a split test with per-variant results: visitors, visits, leads, appointments, shows, sales, net revenue, conversion rates, revenue per visitor, the Bayesian probability each variant beats the control and its relative lift with a 95% interval, plus the verdict, a sample-ratio-mismatch check and daily unique visitors per variant. Revenue is in `revenue_currency`.

MCP tool: get_split_test_report

Get a split test definition

Returns a split test's setup without results: status, variants and weights, public link, domain, assignment mode, query pass-through and auto-stop rules. Use get_split_test_report for performance.

MCP tool: get_split_test

Create a split test

Creates a draft landing-page split test with 2-5 variants and returns it with its public link (`split_url`, /go/<slug> on the shared host or a custom domain). Nothing is served until it is started with start_split_test; measuring results needs the Tracebird pixel (or CRM linking) on the landing pages.

MCP tool: create_split_test

Update a split test

LIVE CHANGE: affects real visitor traffic on the public split link. Confirm with the user first. Changes only the fields you send. Variants (URLs, weights) and the assignment mode can only change while the test is a draft; afterwards only variant names, slug, domain, query pass-through and auto-stop can change. Completed tests can't be edited. Sending variants replaces the whole list (include each kept variant's id).

MCP tool: update_split_test

Delete a split test

LIVE CHANGE: affects real visitor traffic on the public split link. Confirm with the user first. Deletes the test; its public link stops working immediately.

MCP tool: delete_split_test

Duplicate a split test

Copies a test's settings and variants into a new draft named "<name> (copy)" with a fresh link. Results are not copied.

MCP tool: duplicate_split_test

Start or resume a split test

LIVE CHANGE: affects real visitor traffic on the public split link. Confirm with the user first. Starts a draft test or resumes a paused one: the public split link begins sending real visitors to the variants.

MCP tool: start_split_test

Pause a split test

LIVE CHANGE: affects real visitor traffic on the public split link. Confirm with the user first. Pauses a running test so the split link stops splitting traffic. Resume with start_split_test; end it with declare_split_test_winner.

MCP tool: pause_split_test

Declare a split test winner

LIVE CHANGE: affects real visitor traffic on the public split link. Confirm with the user first. Completes the test and sends 100% of the split link's traffic to the chosen variant. Cannot be undone.

MCP tool: declare_split_test_winner

List split link domains

Lists the workspace's custom split link domains with DNS/verification status, the CNAME and TXT records to create, certificate state, usage by tests and which one is the default. `available` is false when this deployment has no custom-domain support. Stale pending domains are re-checked first.

MCP tool: list_split_domains

Connect a split link domain

Adds a custom subdomain (e.g. go.brand.com) for split links and returns the CNAME and TXT records the user must create at their DNS host; the domain goes active once both are verified (use refresh_split_domain). Admin only. Confirm the hostname with the user.

MCP tool: connect_split_domain

Update a split link domain

Renames a domain and/or makes it the workspace default (preselected for new split tests). Admin only.

MCP tool: update_split_domain

Remove a split link domain

LIVE CHANGE: affects the public split links served on this domain. Confirm with the user first. Removes the domain; split tests on it fall back to the shared Tracebird link, so links already shared on this domain stop working. Admin only.

MCP tool: remove_split_domain

Re-check a split link domain

Re-runs the DNS (CNAME + TXT ownership) and Cloudflare certificate checks and returns the updated status. Throttled to one network check per 10 seconds per domain; call it after the user has created the DNS records.

MCP tool: refresh_split_domain_verification

Detect a domain's DNS provider

Looks up where the domain's DNS is hosted (e.g. cloudflare) so you know whether apply_split_domain_cloudflare can set up the records automatically. Read-only lookup.

MCP tool: detect_split_domain_dns

Create the DNS records in the user's Cloudflare zone

LIVE CHANGE: affects the public split links served on this domain. Confirm with the user first. Uses a Cloudflare API token supplied by the user (DNS edit on the domain's zone; used once, never stored) to create the CNAME and TXT records, then re-checks the domain. Admin only.

MCP tool: apply_split_domain_cloudflare

List conversion events

Lists conversion events recorded from CRMs and webhooks (GoHighLevel, HubSpot, custom/Cortana/Calendly/Whop webhooks): leads, appointments, shows and sales, with value, currency, label, the ad / ad set / campaign they were attributed to and the contact (name, email, phone) when known. Ordered oldest first by when Tracebird recorded the event (`created_at`, then id), so incremental sync is: pass the newest `created_at` you saw as `created_since` and follow `next_cursor`. Events are never edited in place except that a sale can later be voided (`voided_at` set) or partly refunded (`refunded_value`); those changes do not move `created_at`, so created_since will not re-deliver them. To catch voids and refunds, periodically re-read a recent window with since/until (by `occurred_at`). Sale amounts are in the event's own `currency` (major units), not converted. Times are ISO 8601 UTC.

MCP tool: list_conversions

Record a lead, appointment, show or sale

Sends one conversion from your own app into Tracebird. It is attributed to an ad (via tracebird_visitor_id from the Tracebird pixel, explicit ad_id / ad_set_id / campaign_id, UTM names, or the contact's earlier lead), appears in revenue, customers and conversion reports, and is forwarded to Meta Conversions API exactly like an event from a custom inbound webhook. Idempotent: sending the same type + external_id again records nothing new and returns deduplicated: true. A sale needs value > 0 (currency defaults to the workspace currency). Link a sale to its lead by sending the same email or phone, or the lead's external_id as lead_id. Events appear under the "Tracebird API" source in Integrations.

MCP tool: record_conversion

List customers

Lists customers: people Tracebird has linked across CRMs, webhooks, Stripe and the Tracebird pixel, with name, email, phone, first/last seen, the ad and campaign that acquired them, which sources saw them and lifetime revenue. Pages are 50 customers; follow next_cursor. Most recently active first by default. Use get_customer for one person's full journey. `revenue` is sales minus refunds summed across sources without currency conversion (mixed currencies are added as-is), so treat it as approximate when the workspace sells in several currencies.

MCP tool: list_customers

Get a customer and their journey

Returns one customer with their full timeline across ad clicks, page views, split-test exposures, leads, appointments, shows, sales, Stripe payments and refunds (newest first), including the ad that drove each step and sale amounts with currency. Use list_customers to find ids.

MCP tool: get_customer

Conversions overview: connected sources, webhooks, attribution model and pixel

The Integrations → Conversions page: GoHighLevel, HubSpot and Whop connections (with import progress), custom/Cortana/Calendly webhook rows (receive `url` shown to admins only), the click attribution model, last-7-day totals, recent events, ads missing tracking and Tracebird pixel status. Use it to find connection ids for the other conversion-source tools.

MCP tool: get_conversions_overview

Create an inbound conversion webhook

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Creates a receive URL (returned as `url`) that a CRM, Zapier or Make posts conversions to. provider `cortana` creates the Cortana row (then add its API key with connect_cortana_api); Calendly and Whop have their own connect tools. Up to 10 webhooks per provider.

MCP tool: create_inbound_webhook

Change an inbound webhook's URL slug

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Renames the slug in the webhook's receive URL; the old URL stops working immediately, so senders must be updated. Returns the new `url`.

MCP tool: rename_inbound_webhook_slug

Delete an inbound webhook

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Deletes the receive URL so it stops accepting events at once; conversions it already recorded stay. Calendly rows are removed with disconnect_calendly.

MCP tool: delete_inbound_webhook

Get the sign-in link to connect GoHighLevel, HubSpot or Whop

These CRMs connect through a browser sign-in that cannot run over the API. Returns `connect_url` plus instructions: ask a signed-in admin to open the link, then use get_conversions_overview to see the new connection. Whop can also be connected with an API key via connect_whop_with_api_key.

MCP tool: get_conversion_source_connect_url

Disconnect GoHighLevel

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Disconnects a GoHighLevel connection: its tokens are erased and no new conversions arrive. Recorded conversions stay. Reconnecting needs a browser sign-in (get_conversion_source_connect_url).

MCP tool: disconnect_ghl

Choose the GoHighLevel history import

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Answers 'import past data?' for a new GoHighLevel connection: days 30, 90 or 365 starts a backfill (leads, appointments, shows, sales) that adds historical conversions and revenue; 0 skips. Advance a running import with step_ghl_import until its import status is done.

MCP tool: choose_ghl_import

Resume a failed GoHighLevel import

Picks a failed GoHighLevel import back up where it stopped (progress kept). Errors if there is no failed import to resume.

MCP tool: resume_ghl_import

Advance running GoHighLevel imports

Runs one bounded batch of every running GoHighLevel import in the workspace (the app does this while the page is open; an hourly job also finishes imports). Call repeatedly, checking get_conversions_overview for the import status.

MCP tool: step_ghl_import

Disconnect HubSpot

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Disconnects a HubSpot connection: its tokens are erased and no new conversions arrive. Recorded conversions stay. Reconnecting needs a browser sign-in (get_conversion_source_connect_url).

MCP tool: disconnect_hubspot

Choose the HubSpot history import

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Answers 'import past data?' for a new HubSpot connection: days 30, 90 or 365 starts a backfill (leads, appointments, shows, sales) that adds historical conversions and revenue; 0 skips. Advance a running import with step_hubspot_import until its import status is done.

MCP tool: choose_hubspot_import

Resume a failed HubSpot import

Picks a failed HubSpot import back up where it stopped (progress kept). Errors if there is no failed import to resume.

MCP tool: resume_hubspot_import

Advance running HubSpot imports

Runs one bounded batch of every running HubSpot import in the workspace (the app does this while the page is open; an hourly job also finishes imports). Call repeatedly, checking get_conversions_overview for the import status.

MCP tool: step_hubspot_import

Connect Whop with an API key

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Connects a Whop company with an API key (needs payment:basic:read and member:email:read; developer:manage_webhook enables real-time events) and imports the last 30 days of payments as sales. Returns an optional `warning`. For one-click OAuth use get_conversion_source_connect_url.

MCP tool: connect_whop_with_api_key

Sync a Whop connection now

Pulls new Whop payments and refunds right away instead of waiting for the hourly sync. Fails if Whop is turned off in Integrations.

MCP tool: sync_whop

Disconnect Whop

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Disconnects a Whop company: its credentials and webhook are removed and no new payments arrive. Recorded sales stay.

MCP tool: disconnect_whop

Save the Cortana API key

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Validates and stores a Cortana REST API key and business id on the Cortana webhook row (create it first with create_inbound_webhook, provider cortana). Enables history import and hourly catch-up of missed deliveries.

MCP tool: connect_cortana_api

Remove the Cortana API key

Erases the stored Cortana API key and business id. The Cortana webhook URL keeps working; delete it with delete_inbound_webhook.

MCP tool: remove_cortana_api

Import Cortana history

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Starts (days 7, 30 or 90) or continues (days 0) a Cortana history import and runs one bounded step. Call repeatedly until the result's `done` is true.

MCP tool: import_cortana_history

Connect Calendly with a personal access token

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Connects Calendly with a Personal Access Token (Calendly paid plan required): Tracebird subscribes to bookings and cancellations and records them as appointments. One Calendly connection per workspace.

MCP tool: connect_calendly

Disconnect Calendly

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Removes the Calendly connection and its webhook subscription (best effort). Recorded appointments stay.

MCP tool: disconnect_calendly

Get the CRM click attribution model

Returns whether GoHighLevel and HubSpot conversions are credited to the contact's first click or last click (first_click is the default).

MCP tool: get_attribution_model

Set the CRM click attribution model

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Switches GoHighLevel and HubSpot between first-click and last-click credit and re-credits past conversions to the other touch, which changes ad-level conversion and revenue numbers everywhere. Returns how many events were swapped.

MCP tool: set_attribution_model

Get the Tracebird pixel install snippet and status

Returns the workspace pixel: the install snippet to paste in the site head, the allowed website domains, event counts and collection health, and the latest installation test (its `test_urls` to open and whether the site reported back). The pixel is created when the first domain is saved with update_pixel_domains.

MCP tool: get_pixel

Save the pixel's allowed website domains

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Replaces the website domains allowed to send pixel events (domain only, e.g. example.com; www is covered). Creates the pixel on first save. Events from other domains are rejected, so removing a domain stops its tracking. Returns the updated pixel.

MCP tool: update_pixel_domains

Start a pixel installation test

Issues a fresh test nonce for the next 15 minutes. Open one of the returned `test_urls` in a browser with the snippet installed, then poll get_pixel until `install_test.seen` is true. Needs at least one saved domain.

MCP tool: start_pixel_install_test

List named conversions

Lists the Tracking & Conversions definitions (name, matched event types / sources / names, Meta event, enabled) with last-90-day counts, plus `can_manage` and whether forwarding to Meta (`capi_enabled`) is on.

MCP tool: list_conversion_definitions

List sources and names a conversion can match

Every connection that sent conversions in the last 90 days with the event types and names (forms, calendars, products) it sent. Use the `key` values in a definition's `sources`.

MCP tool: list_conversion_sources_for_definitions

Conversion activity feed with Meta delivery status

Recent conversion events with which named conversions matched and the Meta delivery status of each. Offset paged.

MCP tool: get_conversion_activity_feed

Create a named conversion

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Defines a conversion (event types + optional sources and names) and the Meta event it is sent as when forwarding to Meta is on.

MCP tool: create_conversion_definition

Update a named conversion

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Replaces the definition's fields (send all of name, event_types, sources, labels, meta_event_name as returned by list_conversion_definitions); omitted optional fields are cleared.

MCP tool: update_conversion_definition

Enable or disable a named conversion

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Turns a conversion on or off; a disabled conversion stops being sent to Meta.

MCP tool: set_conversion_definition_enabled

Duplicate a named conversion

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Creates a copy named '<name> (copy)' with the same matching and Meta event, so it will send duplicate Meta events until edited or disabled.

MCP tool: duplicate_conversion_definition

Delete a named conversion

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Deletes the definition; it is no longer sent to Meta. Recorded conversion events are untouched.

MCP tool: delete_conversion_definition

Retry a failed Meta conversion delivery

Confirm with the user first: this changes how conversions are attributed or sent to Meta. Re-queues a conversion event's failed Meta Conversions API deliveries and sends them now. Needs forwarding to Meta turned on.

MCP tool: retry_meta_delivery

List revenue offers with funnel stage

Settings → Revenue offers, grouped by source: products and prices with their own tag (`stage`: front_end, back_end or null for automatic), `effective_stage`, suggested stage, price, and 90-day sales and revenue. Includes the funnel settings (back-end threshold). Use the offer `key` with set_offer_stage.

MCP tool: list_offers

Tag an offer front-end or back-end

Confirm with the user first: this changes how revenue is attributed and the front-end / back-end figures on dashboards. Sets an offer's funnel stage; `auto` returns it to automatic (the price threshold decides). Dashboard snapshots are refreshed.

MCP tool: set_offer_stage

List revenue streams and what each counts as

Settings → Revenue sources: each payment / deal stream (Stripe account, Whop company, GoHighLevel, HubSpot, webhook) with its `role` (split, threshold, front_end, back_end, none), whether it is automatic, its threshold, 90-day sales and the Stripe-copy check. Use `id` with set_revenue_stream_role.

MCP tool: list_revenue_streams

Set what a revenue stream counts as

Confirm with the user first: this changes how revenue is attributed and the front-end / back-end figures on dashboards. Sets a stream's role: split (both stages, offers by tag/threshold), threshold (both stages, every sale by this stream's own threshold), front_end, back_end, none (ignored), or auto. `threshold` (major currency units) applies only to role threshold.

MCP tool: set_revenue_stream_role

Get revenue settings

Returns the back-end price threshold, the front-end / back-end revenue source settings, the revenue `attribution_model` (which ad a sale is credited to) and the workspace revenue source of truth (auto, stripe, crm or facebook).

MCP tool: get_revenue_settings

Update revenue settings

Confirm with the user first: this changes how revenue is attributed and the front-end / back-end figures on dashboards. Sets the back-end price threshold (major currency units; sales at or above it count as back end), the revenue attribution model (which ad each sale's revenue is credited to; separate from the CRM click model in set_attribution_model) and/or the workspace revenue source of truth used by dashboards. Send at least one field.

MCP tool: update_revenue_settings

Catalog of every integration with its connection status

Lists every integration Tracebird offers (ad platforms, attribution, payments, CRMs, analytics, data sources, tracking) with connection status, account name, last sync, errors and paused state, like the Integrations page. CRM and data-source integrations are only summarised here; manage them with their own tools.

MCP tool: list_integrations

Details of one integration

Returns one integration's status and details: ad accounts with their enabled flag and stored counts (facebook, google_ads), key preview (hyros), connected accounts and 90-day payment totals (stripe), properties (google_analytics), projects and cached-snapshot state (microsoft_clarity) or settings and delivery stats (meta_capi). Secrets are never returned.

MCP tool: get_integration

Last 20 syncs of the ad platforms and HYROS

Returns the 20 most recent sync runs of Facebook, Google Ads and HYROS (status, message, records read, timings). For full filterable history use list_sync_history.

MCP tool: list_recent_sync_runs

Filterable sync history across integrations

Lists past sync runs of every integration, newest first, filtered by provider, status, sync type and time window (the Settings sync history table). Paginate with cursor.

MCP tool: list_sync_history

Sync an integration now

Starts a manual sync for facebook, google_ads, hyros or stripe and waits for it to finish, like "Sync now" in the app. Refused while the integration is turned off or already syncing. Stripe also accepts connection_id (one account) and sync_type backfill.

MCP tool: sync_integration

Stop a running sync

Stops a running facebook, google_ads or hyros sync; it exits cleanly at its next step. Confirm with the user before calling. Returns stopped=false when nothing was running.

MCP tool: cancel_integration_sync

Turn an integration off without disconnecting it

Stops syncing an integration but keeps its data and connection ("Turn off" in the app). mode "all" (default) also hides its data and defers automations; mode "sync" (ghl, hubspot, whop, stripe only) keeps webhooks live. Confirm with the user before calling. Undo with resume_integration.

MCP tool: pause_integration

Turn a paused integration back on

Resumes a paused integration; it becomes due for sync immediately and backfills the gap. Does nothing if it was not paused.

MCP tool: resume_integration

Get the link a signed-in admin opens to connect an OAuth integration

Browser sign-in (OAuth) cannot happen over the API. For facebook, google_ads, google_analytics or stripe this returns connect_url (Tracebird's Integrations page) and instructions for the user to finish; every later step (choosing accounts or a property, sync, disconnect) has its own tool. API-key integrations connect directly with save_hyros_api_key, connect_microsoft_clarity and save_meta_capi_settings.

MCP tool: get_integration_connect_url

Ad accounts the connected login can access

Lists the ad accounts (facebook) or customers (google_ads) the connected login can pick from, queried live from the platform, with selected_ids showing the ones already tracked. Requires the platform to be connected first (get_integration_connect_url).

MCP tool: list_ad_account_choices

Start tracking ad accounts

Adds the chosen ad accounts (ids from list_ad_account_choices) to the workspace for facebook or google_ads and starts their first sync; the plan's ad account limit applies. Confirm with the user before calling. This begins pulling that account's data into Tracebird.

MCP tool: select_ad_accounts

Stop tracking an ad account and delete its data

Removes an ad account from facebook or google_ads and permanently deletes everything synced from it (campaigns, ad sets, ads, daily metrics). Confirm with the user before calling. This cannot be undone; to only pause it use set_ad_account_enabled.

MCP tool: remove_ad_account

Enable or disable an ad account in Tracebird

Turns a tracked ad account on or off for facebook or google_ads. Disabling stops syncing it and deletes its synced data; enabling checks the plan's account limit and the live plan. Confirm with the user before calling. Disabling removes data from Tracebird (not from the ad platform).

MCP tool: set_ad_account_enabled

Connect HYROS with an API key

Validates the HYROS API key against HYROS, stores it encrypted (only a preview is ever shown again) and runs the first sync. Replaces any existing key. Requires a paid plan. Confirm with the user before calling.

MCP tool: save_hyros_api_key

Disconnect an integration and delete its synced data

Disconnects facebook, google_ads, hyros, google_analytics, microsoft_clarity or meta_capi: deletes the stored credential and the data synced with it, and stops syncing. Confirm with the user before calling. This cannot be undone; to only stop syncing use pause_integration. For Stripe use disconnect_stripe_connection.

MCP tool: disconnect_integration

Google Analytics properties the connected login can use

Lists the GA4 properties available to the connected Google account (queried live). Requires Google Analytics to be connected first (get_integration_connect_url).

MCP tool: list_google_analytics_properties

Add a Google Analytics property

Selects the GA4 property (id from list_google_analytics_properties) to the properties whose reports Tracebird shows; earlier properties stay connected. Confirm with the user before calling.

MCP tool: select_google_analytics_property

Connect a Microsoft Clarity project with a Data Export API token

Validates the Clarity Data Export API token (one per Clarity project) by fetching a real snapshot, then stores it encrypted (never shown again). Adds a project, or replaces the token of project_id. Confirm with the user before calling.

MCP tool: connect_microsoft_clarity

Cached Microsoft Clarity UX snapshot

Returns each connected Clarity project with its cached 3-day UX snapshot (sessions, rage and dead clicks, scroll depth, top pages) and connection state. Snapshots refresh from Clarity at most every 6 hours.

MCP tool: get_microsoft_clarity_snapshot

Connected Stripe accounts

Lists the connected Stripe accounts used for conversions (account, live or test mode, last sync, warnings, whether history backfill finished and a sync is running).

MCP tool: list_stripe_connections

Disconnect one Stripe account and delete its imported data

Removes one connected Stripe account and only the payments, refunds and metrics imported from it. Confirm with the user before calling. This cannot be undone. Connection ids come from list_stripe_connections.

MCP tool: disconnect_stripe_connection

Meta Conversions API settings and delivery stats

Returns whether leads and sales are forwarded to a Meta dataset: dataset id, whether an own token is set (never the token), test event code, which events are sent, 7-day delivery stats and the last error. settings is null when it is off.

MCP tool: get_meta_capi_settings

Meta datasets (pixels) available for the Conversions API

Lists the Meta datasets (pixels) owned by the connected Facebook ad accounts, queried live. Empty when Facebook is not connected.

MCP tool: list_meta_capi_datasets

Turn on or update Meta Conversions API forwarding

Saves the Meta dataset and which events (leads, purchases) are forwarded server-side. The optional dataset token is write-only; omit it to use the Facebook connection or keep the stored one. Confirm with the user before calling. This sends customer conversion data to Meta.

MCP tool: save_meta_capi_settings

Recent Meta Conversions API deliveries

Lists the most recent events forwarded to Meta (source_ref, event name, status sent / failed / skipped, attempts, last error), newest first. Use the source_ref of a failed one with retry_meta_capi_delivery.

MCP tool: list_meta_capi_deliveries

Retry a failed Meta Conversions API delivery

Re-queues one failed delivery and sends pending events to Meta right away, like Retry in the app. Confirm with the user before calling. Fails when forwarding is off or the delivery is not in a failed state.

MCP tool: retry_meta_capi_delivery

List connected Google Sheets

Lists the Google Sheets lookup tables connected to the workspace (up to 5) with their columns, mode, row count, sync status and the rule fields they provide.

MCP tool: list_data_sources

List sheet fields usable in rules

Flat list of the {sheet_*} fields that connected Google Sheets expose to automation rules and formulas.

MCP tool: list_data_source_fields

List Google Sheet problems

Problems with connected sheets: unreadable sheets, degraded matches and rules that point at columns that no longer exist.

MCP tool: list_data_source_issues

Get a connected Google Sheet

One connected Google Sheet with its columns, mode, match column, status and last error.

MCP tool: get_data_source

Preview rows of a Google Sheet

The first rows of the synced copy of a sheet (default 25, max 100), as column to value maps.

MCP tool: preview_data_source_rows

Connect a Google Sheet

Connects a Google Sheet shared as 'anyone with the link can view' and imports its rows (max 5 sheets per workspace). Mode defaults to what the sheet's shape suggests; match_column applies to lookup mode.

MCP tool: connect_data_source

Update a Google Sheet's name, mode or match column

Renames a connected sheet, switches its mode, or changes the column used to match rows to ads. Changing the match column re-indexes the synced rows.

MCP tool: update_data_source

Refresh a Google Sheet now

Re-downloads the sheet immediately. A failed download is recorded on the source (status and error) and returned rather than raised.

MCP tool: refresh_data_source

Remove a Google Sheet

Removes a connected sheet and its synced rows. Rules that use its fields stop matching; the response lists them. Confirm with the user before calling.

MCP tool: delete_data_source

Supabase source status

Connection state of the Supabase Facebook Ads source: project, mapping, last sync, errors, and whether one-click OAuth sign-in is available. Secrets are never returned.

MCP tool: get_supabase_status

Get the Supabase sign-in link

Returns the link where a workspace admin signs in with Supabase in a browser (OAuth cannot run over the API). Afterwards use list_supabase_projects and select_supabase_project. Alternatively connect with a project URL and key.

MCP tool: get_supabase_connect_url

Connect Supabase with a project URL and key

Verifies the key can read the schema, stores it encrypted and returns the discovered tables with a suggested mapping. Finish with save_supabase_mapping.

MCP tool: connect_supabase_with_key

List Supabase projects after sign-in

Projects available to the Supabase account that signed in through the connect link. Requires that sign-in to have happened first.

MCP tool: list_supabase_projects

Pick the Supabase project to read

After sign-in, selects a project by ref; its key is fetched and stored encrypted. Returns the discovered tables with a suggested mapping.

MCP tool: select_supabase_project

Discover Supabase tables and the mapping shape

Tables and columns of the connected project, a suggested mapping, the saved mapping, and mapping_shape describing every mappable entity and field. Projects that hide their schema return no tables; use get_supabase_table_columns.

MCP tool: list_supabase_tables

List the columns of a Supabase table

Columns of one table, read from a sample row; for projects that do not expose their schema description.

MCP tool: get_supabase_table_columns

Save the Supabase table mapping

Imported rows overwrite this workspace's Facebook ad data (campaigns, ad sets, ads and daily metrics) like a Meta sync, so confirm with the user before calling. Validates and saves which tables and columns hold campaigns, ad sets, ads and daily metrics, marks the source connected and starts the first import in the background.

MCP tool: save_supabase_mapping

Sync Supabase now

Imported rows overwrite this workspace's Facebook ad data (campaigns, ad sets, ads and daily metrics) like a Meta sync, so confirm with the user before calling. Reads the mapped tables immediately (it also runs hourly). Returns a summary message and the rows read.

MCP tool: sync_supabase

Disconnect Supabase

Removes the stored Supabase credentials and stops syncing. Already imported ad data stays. Confirm with the user before calling.

MCP tool: disconnect_supabase

BigQuery source status

Connection state of the BigQuery Facebook Ads source: account, project, dataset, mapping, last sync, errors, and whether Google sign-in is available. Credentials are never returned.

MCP tool: get_bigquery_status

Get the Google sign-in link for BigQuery

Returns the link where a workspace admin signs in with Google (bigquery.readonly) in a browser; OAuth cannot run over the API. Afterwards list projects and datasets. Alternatively connect with a service-account key.

MCP tool: get_bigquery_connect_url

Connect BigQuery with a service-account key

Verifies the service-account key JSON by fetching a token, then stores it encrypted. Next list projects and datasets and select a dataset.

MCP tool: connect_bigquery_with_service_account

List BigQuery projects

Google Cloud projects the connected credentials can read.

MCP tool: list_bigquery_projects

List datasets of a BigQuery project

Lists the BigQuery datasets in one Google Cloud project that the connected credentials can read.

MCP tool: list_bigquery_datasets

Pick the BigQuery dataset to read

Saves the project and dataset and returns its tables with a suggested mapping, the saved mapping and mapping_shape. Re-selecting the same dataset keeps the mapping; another dataset clears it. Call again any time to re-list tables.

MCP tool: select_bigquery_dataset

Save the BigQuery table mapping

Imported rows overwrite this workspace's Facebook ad data (campaigns, ad sets, ads and daily metrics) like a Meta sync, so confirm with the user before calling. Validates and saves which tables and columns of the selected dataset hold campaigns, ad sets, ads and daily metrics, marks the source connected and starts the first import in the background.

MCP tool: save_bigquery_mapping

Sync BigQuery now

Imported rows overwrite this workspace's Facebook ad data (campaigns, ad sets, ads and daily metrics) like a Meta sync, so confirm with the user before calling. Queries the mapped tables immediately (it also runs hourly). Returns a summary message and the rows read.

MCP tool: sync_bigquery

Disconnect BigQuery

Removes the stored BigQuery credentials and stops syncing. Already imported ad data stays. Confirm with the user before calling.

MCP tool: disconnect_bigquery