Brand demand#

Track estimated branded-search demand, competitor Share of Search, and optional first-party Google Search Console observations.

Authentication required

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

GET /v1/brand-demand/config#

Fetch the workspace Brand Demand configuration, including own brand, competitors, exact terms, markets, review state, and Search Console status.

bash

GET /v1/brand-demand/config?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.

PUT /v1/brand-demand/config#

Update the active Brand Demand own brand, competitors, exact terms, and markets by replacing the configuration. Owners only.

Owner only

bash

PUT /v1/brand-demand/config
Authorization: Bearer {token}
Content-Type: application/json

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
ownBrand	`object`	Required
competitors	`Array<object>`	Required
markets	`Array<object>`	Required

Response#

Returns { data, _meta } with the result.

GET /v1/brand-demand/report#

Fetch 12 complete months of estimated branded-search demand and Share of Search for one market, with optional observed Search Console metrics reported separately.

bash

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

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
marketId	`string (UUID)`	—	Unique identifier (UUID v4).

Response#

Returns { data, _meta } with the result.

GET /v1/brand-demand/moments#

List the months where searches for your own brand rose or fell well outside their usual level, each with what your team said ran that month or that it was not your marketing.

bash

GET /v1/brand-demand/moments?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.

POST /v1/brand-demand/moments/answer#

Record what drove a month where your brand searches moved: link the activities or campaigns that ran, mark it as not your marketing, or reopen the question.

bash

POST /v1/brand-demand/moments/answer
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "month": "...",
  "answer": "...",
  "activity_ids": "...",
  "campaign_ids": "..."
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
month	`string`	Required	First day (YYYY-MM-01) of the month the moment covers.
answer	`'ran' \| 'external' \| 'reopen'`	Required	ran: link the activities or campaigns that ran that month. external: the movement was not driven by your marketing. reopen: clear the answer.
activityIds	`Array<string (UUID)>`	Required	Activities that ran that month, for the ran answer.
campaignIds	`Array<string (UUID)>`	Required	Campaigns that ran that month, for the ran answer.

Response#

Returns { data, _meta } with the result.