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/organization/metrics#

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

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization identifier.

Response#

Returns { data, _meta } with the result.

GET /v1/reporting/organization/metrics/history#

Fetch organization metrics over time with a configurable lookback window.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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 cost 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 cost read alongside traffic and brand signals on one timeline.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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/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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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 organization-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

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&start_date=...&end_date=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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, cost, impressions, social engagement, delivery coverage, denominator-aware CPM and Social CPE, freshness, provenance, and data-quality warnings.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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, cost, CPM, and CPE.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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, cost, CPM, and CPE over time with a configurable lookback window.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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, cost, CPM, and CPE.

bash

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

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&activity_id=7f2e9b34-5c81-4d6a-8e07-9a3b1c5d2f02
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_ids=...&days_back=30
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&days_back=30&audience=...
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
organizationId	`string (UUID)`	Required	Organization 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?organization_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&campaign_id=3a8d1f56-9e42-4b7c-a1d8-6f0e2b9c4a03
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data, _meta } with the result.