---
title: "Branded-search detail and its TikTok correlation"
method: POST
path: "/halo/branded-search"
tags: ["Halo Effect Tracker"]
---

# Branded-search detail and its TikTok correlation

`POST /halo/branded-search`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/halo/branded-search`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Amazon branded search is the cleanest halo signal there is: nobody searches a brand by name unless something put it in their head, and on TikTok-driven brands that something is usually a video. This returns the daily branded-search volume and click share for the window, the window totals, the peak day, and the Pearson correlation against TikTok views at the requested ``lag_days`` — the same regression the analysis endpoint runs. 

``top_search_terms`` is always null: Amazon reports branded-search volume per ASIN per day, not the query strings, so there is no term list to return. The field exists so it can be filled later without a breaking change. 

Pass ``asins`` to scope to specific products; omit for every tracked ASIN. An empty ``series`` means branded search isn't tracked for this shop (check ``branded_search`` on ``GET /halo/channels``). Single-shop only.

## Request body

- HaloBrandedSearchRequest: POST /halo/branded-search body.
  - `start_date` string, date, nullable: Inclusive window start (YYYY-MM-DD).
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD).
  - `asins` string[], nullable: Restrict to these ASINs. Omit for every tracked ASIN.
  - `lag_days` integer: Shift TikTok views forward N days before correlating.

## Response `200`

Successful Response

- HaloBrandedSearchResponse
  - `shop_id` integer, required
  - `start_date` string, required
  - `end_date` string, required
  - `lag_days` integer, required
  - `asins` string[], nullable: The ASIN filter applied, echoed back.
  - `total_search_terms` integer, nullable: Sum of daily branded-search volume.
  - `average_click_share` number, nullable: Mean of the daily click-share values.
  - `peak_date` string, nullable: Date of the highest branded-search volume.
  - `peak_search_terms` integer, nullable
  - `correlation` HaloCorrelation
    - `channel` string, nullable
    - `r` number, nullable: Pearson r, 4 dp.
    - `p_value` number, nullable: Two-sided p-value, 6 dp. Below 0.05 is the usual bar.
    - `label` string, nullable: Weak / Moderate / Strong (standard statistical bands).
  - `top_search_terms` string[], nullable: Always null. Amazon's report gives us branded-search VOLUME per ASIN per day, not the query strings, so no term list exists to return. Reserved so the field can be populated without a breaking change if term-level data is ever ingested.
  - `series` HaloBrandedSearchPoint[], required
    - `date` string, required
    - `search_terms` integer, nullable
    - `click_share` number, nullable

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 1 info
  - api operation id `halo_branded_search_halo_branded_search_post` removed and replaced with `halo_branded_search`

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/halo/branded-search/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)