Forecast, CAC, finance & modeling
Read-only tools. Forecasts, Signal CAC, accounting data, marketing-mix-model results and deterministic report templates.
| Tool | Purpose |
|---|---|
get_forecast | Performance forecast |
get_signal_cac | Signal CAC by channel |
get_finance | Financials (books) |
get_mmm_results | Marketing mix model results |
run_report | Run a report template |
get_forecast
Performance forecast
Projected daily performance from the forecast mart (BigQuery AI.FORECAST fitted over recent actuals), organization-wide or filtered to one product, network, account or campaign. mode=summary (default) returns projected totals for the window; mode=daily returns the projected per-day series. These are MODEL PROJECTIONS, not observed data: label them as forecasts, never add them into an actuals total, and do not present a projected value as something that happened. The mart holds a short FORWARD horizon (about a week ahead, rebuilt nightly), and the window simply selects which of those days come back — a window entirely in the past returns nothing, which is expected rather than a failure. Omit both dates for the default window: the last 30 complete days ending yesterday.
Posture: read-only · Module gate: forecast · REST: POST /api/v1/tools/get_forecast
| Argument | Type | Required | Notes |
|---|---|---|---|
account_id | string | no | Filter to one ad account id. (length 1–128) |
ad_network_id | string | no | Filter to one network: facebook_ads | google_ads | tiktok_ads | linkedin_ads | bingads. (length 1–64) |
campaign_id | string | no | Filter to one campaign id. (length 1–128) |
end_date | string | no | Window end, YYYY-MM-DD (inclusive). (pattern ^\d{4}-\d{2}-\d{2}$) |
mode | summary | daily | no | summary (default) = projected totals for the window; daily = the projected per-day series. |
product_id | string | no | Filter to one product id from the org context. (length 1–128) |
start_date | string | no | Window start, YYYY-MM-DD (inclusive). Omit both dates for the default window: the last 30 complete days ending yesterday. (pattern ^\d{4}-\d{2}-\d{2}$) |
get_signal_cac
Signal CAC by channel
Cost per attributed conversion from Signal's spend-attribution mart, by date, attribution model, channel and campaign: spend, credited_conversions and CAC. Use it for "what does a conversion cost by channel" once Signal is tracking conversions. Rows exist ONLY where credited conversions join ad spend on matching campaign names, so an empty result is a valid state — it means nothing has joined yet, not that CAC is zero and not that the tool failed. Because credit is split by attribution model, always state which model a CAC figure comes from. Requires the Signal spend/CAC mart: without the entitlement this returns a plan refusal rather than empty rows.
Posture: read-only · Module gate: signal_cac · REST: POST /api/v1/tools/get_signal_cac
| Argument | Type | Required | Notes |
|---|---|---|---|
start_date | string | no | Since date, YYYY-MM-DD (default: 90 days ago). The window always runs from here through the latest available day; there is no end_date. (pattern ^\d{4}-\d{2}-\d{2}$) |
get_finance
Financials (books)
Financials read straight from this organization's books (QuickBooks or Xero). Pick the report: kpis (monthly revenue, COGS and margins), pl (P&L rows by account), balances (balance-sheet lines including cash), ar_aging (receivables by age bucket), ap_aging (payables by age bucket), or marketing_bridge (ad spend against revenue: MER, blended CAC, spend as a percentage of revenue). since sets the earliest month, default 13 months back. These are ACCOUNTING numbers on the organization's own calendar and recognition rules — they will not match ad-platform revenue columns, and marketing_bridge is the intended place to compare the two. Requires the Margin module and a synced accounting connector; without it you get a plan refusal, and with no synced books an explicit "no accounting data" answer.
Posture: read-only · Module gate: finance · REST: POST /api/v1/tools/get_finance
| Argument | Type | Required | Notes |
|---|---|---|---|
report | kpis | pl | balances | ar_aging | ap_aging | marketing_bridge | yes | Which financial report to return — see the tool description for each. |
since | string | no | Earliest month to include, YYYY-MM-DD (default: 13 months back). (pattern ^\d{4}-\d{2}-\d{2}$) |
get_mmm_results
Marketing mix model results
The latest COMPLETED marketing-mix-model run per outcome KPI and model type (Meridian and/or Robyn): model fit (R², NRMSE), per-channel contribution share, ROI and marginal ROI, plus any stored budget-optimization output. outcome_variable filters to one KPI. These are MODEL ESTIMATES over a training window, not measured attribution: report them as modeled contribution, quote the fit statistics alongside any ROI you cite, and note the run's completed_at — a stale run describes an old media mix. Contribution shares answer "what is driving outcomes", while get_channels answers "what did each channel actually spend and produce". Requires Compass.
Posture: read-only · Module gate: compass · REST: POST /api/v1/tools/get_mmm_results
| Argument | Type | Required | Notes |
|---|---|---|---|
outcome_variable | string | no | Filter to one outcome variable (the KPI the model was trained to explain). Omit to get every outcome the org has trained. (length 1–128) |
run_report
Run a report template
Run a versioned, deterministic report template. The same template over the same window always produces identical tables — the fetches are fixed and the math is precomputed — so prefer this over assembling the same story by hand from several tools. Templates: performance_recap (this period against the previous one, top campaigns, biggest movers), budget_pacing (expected vs actual spend for the current budget period), signal_attribution (credit by channel and model plus CAC), creative_review (winners and losers with attribute insights), finance_snapshot (P&L KPIs plus the marketing bridge). Each template reads the same gated tools you would call yourself: a multi-source template (performance_recap, creative_review, finance_snapshot) fills the sections it can and leaves the rest empty, while a single-source one (budget_pacing) comes back as a plain failure carrying the reason — for example "no budget period covers this date". The payload is designed to be rendered as tables: summarize the headline movements and name the window, do not restate every row. Omit both dates for the default window: the last 30 complete days ending yesterday.
Posture: read-only · Module gate: none (needs only the agent entitlement) · REST: POST /api/v1/tools/run_report
| Argument | Type | Required | Notes |
|---|---|---|---|
template | performance_recap | budget_pacing | signal_attribution | creative_review | finance_snapshot | yes | Which report template to run. |
end_date | string | no | Window end, YYYY-MM-DD (inclusive). (pattern ^\d{4}-\d{2}-\d{2}$) |
start_date | string | no | Window start, YYYY-MM-DD (inclusive). Omit both dates for the default window: the last 30 complete days ending yesterday. (pattern ^\d{4}-\d{2}-\d{2}$) |