Marketing overview#
Read the whole marketing program for a date range: headline figures against the previous window, the week-by-week timeline of what ran and what moved, the weeks that stood out, Brandwave's verdict, a stakeholder brief, and recommended next actions.
Authentication required
Authorization header. See the Authentication guide for setup instructions.GET /v1/marketing/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.
GET /v1/marketing/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/marketing/timeline#
Retrieve the marketing record week by week, a few calendar months at a time, newest first: what ran each week (activities and campaigns), what it cost, and what moved (brand search impressions, sessions, visits from linked promo codes and tagged links, success events such as sign ups, and customers naming the marketing when asked how they heard about you). Each week carries the usual level of every series from the weeks before it and flags the ones that moved well above or below it. Use nextEndDate to page back to the start of the record. Observations only; no causal attribution.
GET /v1/marketing/timeline?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&end_date=...
Authorization: Bearer {token}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| endDate | string | Required | Last day to include (YYYY-MM-DD), usually today. The page covers whole calendar months ending with this date’s month. |
| months | integer | — | Calendar months to return, newest first (1-6, default 3). |
Response#
Returns { data, _meta } with the result.
GET /v1/marketing/long-view#
Retrieve the long view of the marketing program: 12 calendar months by default (3-24) of what went out against the slow measures that brand work moves. Each month counts the activities that went live by job: Build (work that grows awareness over months, such as podcasts, creators and PR), Be findable (work that makes the brand show up when someone looks, such as listings and backlinks) and Convert (work that nudges people who already know the brand, such as paid ads and in-person events), the running total of Build work since the first activity, spend, modeled monthly brand searches, Share of Search against competitors, website visits, success events, and customers who named the marketing when asked how they found you. Measures whose source is not connected are null. It shows what coincided over time and does not assign attribution.
GET /v1/marketing/long-view?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&end_date=...
Authorization: Bearer {token}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| endDate | string | Required | Last day to include (YYYY-MM-DD), usually today. The view covers whole calendar months ending with this date’s month. |
| months | integer | — | Calendar months to return, oldest first (3-24, default 12). |
Response#
Returns { data, _meta } with the result.
GET /v1/marketing/ladder#
Retrieve the marketing ladder for a date range, starting at the top: is the success metric moving (its count in the workspace's own words, visits through linked promo codes and tagged links, the share of customers who named marketing when asked how they found you), are people interested (brand searches a month, clicks from brand searches, followers, interest actions), did people find you (impressions, site visits, visits from search and social), and what was done (activities running in the range by job: Build, Be findable, Convert, with how many started in it and spend; work that started earlier counts while it is still live, and its spend stays with the range it started in). Each figure compares with the previous window of the same length; brand searches compare month over month. Observations only; no causal attribution.
GET /v1/marketing/ladder?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/marketing/compare#
Retrieve activities in a date range grouped by the job they do (Build, Be findable, Convert, or none yet), then by channel, with spend, activity count and impressions beside direct evidence: visits through promo codes and tagged links, and results those codes, links and customer answers named. Cost per result is given for Convert work only, because Build work shows up over months in brand searches and followers, and Be findable work in search clicks and visits. A channel's direct evidence sits with the job that spent most on it. These are observations, with no causal attribution.
GET /v1/marketing/compare?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/marketing/following#
Retrieve Following: how many people chose to hear more from the brand, month by month. It totals followers across the social accounts the brand posts from (YouTube subscribers and TikTok fans count as followers) at the last reading of each month, with the change on the month before, and lists each account with its latest count and how that changed since its first reading in the window. 12 calendar months by default (3-24).
GET /v1/marketing/following?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&end_date=...
Authorization: Bearer {token}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| endDate | string | Required | Last day to include (YYYY-MM-DD), usually today. Months run to the end of this date’s month. |
| months | integer | — | Calendar months to return, oldest first (3-24, default 12). |
Response#
Returns { data, _meta } with the result.
GET /v1/marketing/site-visits#
Retrieve visits to the site (GA4 sessions) month by month, split by where they came from using GA4 default channel groups such as Organic Search, Direct, Referral and Organic Social, with the totals for each source across the window, and the clicks from searches for the brand by name over the same months (from Search Console, null when it has no data). Those clicks are part of Organic Search. siteTraffic says whether Google Analytics is connected, still on its first sync, or no longer connected. 12 calendar months by default (3-24).
GET /v1/marketing/site-visits?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&end_date=...
Authorization: Bearer {token}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| endDate | string | Required | Last day to include (YYYY-MM-DD), usually today. Months run to the end of this date’s month. |
| months | integer | — | Calendar months to return, oldest first (3-24, default 12). |
Response#
Returns { data, _meta } with the result.
GET /v1/marketing/month#
Retrieve one calendar month of the marketing record, the content of the "So what?" page: the activities that went live with their jobs (Build, Be findable or Convert) and what the month cost, thirteen months of the long view ending with that month so it can be compared with the month before and the same month last year, the weeks in the month that stood out, and the channels that showed up or stayed quiet and the blind spots over the three months to its end. It also says whether a read-only link to the page is live. Observations only; it does not assign attribution.
GET /v1/marketing/month?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01&month=...
Authorization: Bearer {token}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| month | string | Required | Calendar month in the form YYYY-MM. |
Response#
Returns { data, _meta } with the result.
POST /v1/marketing/month/share#
Create the read-only link to one month of the "So what?" page, or return the live one. Anyone with the link can open the page without an account until it is revoked.
POST /v1/marketing/month/share
Authorization: Bearer {token}
Content-Type: application/json
{
"workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
"month": "..."
}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| month | string | Required | Calendar month in the form YYYY-MM. |
Response#
Returns { data, _meta } with the result.
DELETE /v1/marketing/month/share#
Revoke the read-only link to one month of the "So what?" page.
DELETE /v1/marketing/month/share
Authorization: Bearer {token}
Content-Type: application/json
{
"workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
"month": "..."
}Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string (UUID) | Required | Workspace identifier. |
| month | string | Required | Calendar month in the form YYYY-MM. |
Response#
Returns { data, _meta } with the result.
GET /v1/marketing/verdict#
Get Brandwave's reading of whether marketing is working for a date range: weeks that stood out because an outcome (brand search, sessions, linked visits, success events, customers naming the marketing) rose clearly above usual, with the activities that started in them; channels that showed up because promo codes, tagged links or customer answers name them; Convert channels (paid media) with spend that have been quiet so far, while Build channels are left to the long view because their effect shows over months; and the blind spots, meaning sources to connect or set up for a fuller reading. Each statement carries its rule, a confidence word (high, medium, low) and the signals it read. Fixed rules over the record, not a model, and coincidence in time rather than causal attribution.
GET /v1/marketing/verdict?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/marketing/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.
GET /v1/marketing/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/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.
GET /v1/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/marketing/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.
GET /v1/marketing/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.