Reporting#

Access decision-ready portfolio, comparison, briefing, recommendation, readiness, and closeout workflows alongside calculated metrics and historical trends.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/reporting/workspace/metrics#

Fetch workspace-level metrics including total expenses, impressions, social engagement, delivery coverage, and denominator-aware CPM and Social CPE.

bash

GET /v1/reporting/workspace/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/workspace/metrics/history#

Fetch workspace metrics over time with a configurable lookback window.

bash

GET /v1/reporting/workspace/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/analytics/history#

Fetch daily Google Analytics site metrics (sessions, users, page views) and success-metric event counts for a date range, zero-filled for days without data.

bash

GET /v1/reporting/analytics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/spend/history#

Fetch daily recorded marketing spend and a running cumulative total for a date range. Each spend is attributed to the day its activity ran (publish date for social content, start date for other channels) and days without spend are zero-filled, so budget and spend read alongside traffic and brand signals on one timeline.

bash

GET /v1/reporting/spend/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/performance/summary#

Assess whether marketing is working for a date range using the evidence chain: spend (spend, activities, campaigns, delivery coverage), awareness (modeled brand search volume, Share of Search, impressions, Search Console brand impressions), traffic (sessions, users, sessions from linked promo codes and tagged links), and results (success-event counts, customer-reported HDYHAU attribution share, campaign reported outcomes). Spend, traffic, and results figures compare the window with the previous window of the same length; brand search volume is a monthly estimate compared with the month before it, which its own comparison field states. Coverage gaps name the connections or data that would sharpen the picture. Returns figures, not a verdict sentence. Evidence only; no causal attribution.

bash

GET /v1/reporting/performance/summary?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/performance/moments#

Retrieve the weeks in a date range where marketing evidence moved: spend, brand search impressions, sessions, sessions from linked promo codes and tagged links, success events, or customer-reported HDYHAU marketing mentions that landed well above or below their trailing weekly median. Each moment lists the activities, campaigns, and campaign reported outcomes live that week so a reader can judge what coincided. Quiet windows return the biggest movers below the threshold instead of nothing. Read weeksEvaluated beside weeksInWindow: a week with no data behind it, or whose preceding weeks are all zero, has no baseline to be compared against and is counted in only one of them. Observations only; no causal attribution.

bash

GET /v1/reporting/performance/moments?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/performance/channels#

Retrieve evidence by channel for a date range: each channel type with spend (social media, broadcast, out of home, print, events, podcasts, PR articles) walked across the evidence chain with spend and activity count, impressions, sessions from linked promo codes and tagged links, linked success events, and customer-reported HDYHAU mentions, plus a corroboration count of how many of the four steps hold direct evidence. Cells are null when the source that could see them is not connected. Nothing is inferred or attributed.

bash

GET /v1/reporting/performance/channels?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/analytics/hdyhau-evidence#

Retrieve a summary of GA4 How Did You Hear About Us (HDYHAU) custom-dimension values for a date range, including raw responses, normalized source categories, response coverage, creator-marketing relevance, data-quality flags, and a daily evidence timeline. This does not assign conversions to creators or campaigns.

bash

GET /v1/reporting/analytics/hdyhau-evidence?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

PUT /v1/reporting/analytics/hdyhau-mapping#

Create or update a reusable workspace-specific mapping that normalizes one raw GA4 HDYHAU response value for a dimension API name into a source label and category for future reporting. This changes classification only and does not assign attribution.

bash

PUT /v1/reporting/analytics/hdyhau-mapping
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "dimension_api_name": "...",
  "raw_value": "...",
  "normalized_value": "...",
  "category": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
dimensionApiName	`string`	Required
rawValue	`string`	Required
normalizedValue	`string`	Required
category	`'creator' \| 'organic_social' \| 'broadcast' \| 'out_of_home' \| 'print' \| 'podcast' \| 'search' \| 'referral' \| 'paid' \| 'events' \| 'other' \| 'unknown'`	Required	Normalized HDYHAU source category.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/analytics/direct-signals#

Retrieve directly observed GA4 promo-code and manually tagged UTM-link evidence for a date range, including sessions, daily users, selected success outcomes, explicit creator/campaign/activity mappings, general referral-channel buckets (e.g. Facebook, Google organic, an AI assistant) with a per-bucket traffic summary, and zero-filled timeline data. This reports observed evidence and does not infer attribution.

bash

GET /v1/reporting/analytics/direct-signals?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
startDate	`string`	Required	First day of the range (YYYY-MM-DD, inclusive).
endDate	`string`	Required	Last day of the range (YYYY-MM-DD, inclusive).

Response#

Returns { data, _meta } with the result.

PUT /v1/reporting/analytics/direct-signals/:signalId/mapping#

Update one discovered GA4 promo code or manually tagged UTM link by mapping it to exactly one Brandwave creator, campaign, or activity, grouping it under one general referral-channel bucket (e.g. Facebook, Google organic, an AI assistant) when it cannot be tied to a specific entity, or removing its existing mapping. The association is mutually exclusive, applies to all observed sessions, users, and outcomes for that signal, and does not infer causal attribution.

bash

PUT /v1/reporting/analytics/direct-signals/:signalId/mapping
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "association": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
signalId	`string (UUID)`	Required	Discovered GA4 direct-signal identifier.
association	`unknown \| null`	Required	Exactly one association - a Brandwave creator, campaign, or activity, or a general referral-channel bucket - or null to remove the mapping.

Response#

Returns { data, _meta } with the result.

PUT /v1/reporting/analytics/direct-signals/:signalId/ignored#

Ignore one discovered GA4 promo code or manually tagged UTM link as noise, or restore a previously ignored one. Ignored signals are hidden from the default reporting view and excluded from its headline counts, but retain their observed sessions, users, and outcomes and can be restored at any time. This changes triage state only and does not infer attribution.

bash

PUT /v1/reporting/analytics/direct-signals/:signalId/ignored
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "ignored": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
signalId	`string (UUID)`	Required	Discovered GA4 direct-signal identifier.
ignored	`boolean`	Required	True to ignore the signal as noise, false to restore it for review.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/campaign/metrics#

Fetch metrics for a single campaign including ISO currency, budget, spend, impressions, social engagement, delivery coverage, denominator-aware CPM and Social CPE, freshness, provenance, and data-quality warnings.

bash

GET /v1/reporting/campaign/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to get metrics for.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/campaign/metrics/history#

Fetch campaign metrics over time with a configurable lookback window.

bash

GET /v1/reporting/campaign/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/creator/metrics#

Fetch metrics for a single creator including activity counts, follower totals, impressions, engagement, spend, CPM, and CPE.

bash

GET /v1/reporting/creator/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&creator_id=9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
creatorId	`string (UUID)`	Required	Creator identifier to get metrics for.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/creator/metrics/history#

Fetch a creator's follower count, impressions, engagement, spend, CPM, and CPE over time with a configurable lookback window.

bash

GET /v1/reporting/creator/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&creator_id=9b4c2e78-1a53-4f6d-b8e9-0c7a5d3f1e04
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
creatorId	`string (UUID)`	Required	Creator identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/activity/metrics#

Fetch metrics for a single activity including impressions, engagement, spend, CPM, and CPE.

bash

GET /v1/reporting/activity/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	Required	Activity identifier to get metrics for.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/activity/metrics/history#

Fetch an activity's metrics over time with a configurable lookback window.

bash

GET /v1/reporting/activity/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
activityId	`string (UUID)`	Required	Activity identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/reporting/campaign/portfolio#

Retrieve decision-ready portfolio health as the preferred starting point for broad campaign-health questions, including active, scheduled, completed, draft, and attention counts; budget and spend totals; brief completeness; evidence quality; priorities; and recommended next actions.

bash

GET /v1/reporting/campaign/portfolio?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
daysBack	`integer`	Required	Trailing window used for campaign changes and portfolio findings (1-365).

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/campaign/comparison#

Retrieve the preferred comparison workflow for selected campaigns over a trailing period, including current values, historical changes, denominator-aware efficiency metrics, ISO currency, evidence quality, and plain-language findings.

bash

GET /v1/reporting/campaign/comparison?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_ids=...&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignIds	`Array<string (UUID)>`	Required	Campaign identifiers to compare.
daysBack	`integer`	Required	Trailing comparison window (1-365 days).

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/marketing-brief#

Create the preferred stakeholder-ready executive or practitioner brief for a trailing period with a headline, highlights, risks, decisions required, recommended actions, campaign evidence, ISO currency, and measurement limitations.

bash

GET /v1/reporting/marketing-brief?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&days_back=30&audience=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
daysBack	`integer`	Required	Trailing reporting window (1-365 days).
audience	`'executive' \| 'practitioner'`	Required	Intended audience and level of operational detail for the brief.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/recommendations#

Retrieve the preferred next-decision workflow with deterministic evidence-backed recommendations about what to investigate, maintain, or consider, including priority, confidence, rationale, supporting evidence, and campaign links.

bash

GET /v1/reporting/recommendations?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/campaign/readiness#

Assess whether a campaign is ready to launch by reviewing its summary, objective, audience, desired outcomes, planned channels, dates, owner, budget, and linked activities.

bash

GET /v1/reporting/campaign/readiness?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to assess before launch.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/campaign/closeout#

Generate a campaign closeout or review with recorded performance, ISO currency, evidence quality, limitations, and recommended follow-up actions without claiming causal attribution.

bash

GET /v1/reporting/campaign/closeout?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
campaignId	`string (UUID)`	Required	Campaign identifier to summarize for closeout or review.

Response#

Returns { data, _meta } with the result.