CopyHero
Back to CopyHero

Get Cluster Growth

GET
/api/v1/watchlist/universe/growth

Rank the active layout's clusters by how many watchlist products the viewer's subscribed competitors added into each within the window (counts are store-filtered + subscription-gated, NOT the store-unfiltered lifetime cluster size), ordered per sort_by. No active layout / no subscription / no points in range → empty data, never a 404.

Authorization

HTTPBearer
headerAuthorizationBearer <token>

Query Parameters

window_days?Window Days

Trailing window size in epoch days, measured back from the newest product day in the viewer's store-filtered set. 1 is the last complete UTC day in that set — the day before the layout's build day when the newest product day is that build day (the nightly refit leaves it partial), otherwise the newest product day itself — not the last 24 hours. Ignored when both start_day and end_day are given.

Range1 <= value
Default30
start_day?|

Explicit window start (UTC epoch day). When BOTH start_day and end_day are given they override window_days as a closed range.

end_day?|

Explicit window end (UTC epoch day). See start_day.

limit?Limit

Top-N clusters by the requested sort_by (max 200).

Range1 <= value <= 200
Default25
sort_by?Sort By

Ranking order: 'added' (default) — products added desc; 'rate' — growth rate over the window (added / pre-window lifetime base) desc, with clusters entirely new in the window ranked first.

Default"added"
Value in"added""rate"
stores?array<string>|

Competitor storefront URLs to narrow the counts to. Narrows within the subscription gate; never widens it.

store_tags?array<>|

Only stores the viewer tagged with any of these tags (OR within the list, AND against every other filter). Narrows within the subscription gate; never widens it — tags matching no subscribed store yield an EMPTY result, never an unfiltered one.

Response Body

Successful Response

application/json
  1. response

Cluster-growth ranking over [window_start_day, window_end_day] (both UTC epoch days). The trailing window is half-open on the start. window_days=1 ends on the last complete UTC day: the day before max_ts_day when that day is the active layout's build day, otherwise max_ts_day. Only clusters with added > 0 are returned, capped at the request limit, sorted by the requested sort_by: added desc (default) or growth rate desc with entirely-new-in-window clusters first. No active layout / no subscription / no points in range → empty data (window days 0), never a 404.

data*array<>
window_start_day*Window Start Day
window_end_day*Window End Day
layout_built_at*|

UTC created_at of the active layout version. Null when no layout is active.

Example Request
curl -X GET 'https://app.copyhero.app/api/v1/watchlist/universe/growth'
Example Response
{  "data": [    {      "cluster_key": 0,      "label": "string",      "color": "string",      "added": 0,      "lifetime_count": 0    }  ],  "window_start_day": 0,  "window_end_day": 0,  "layout_built_at": "2019-08-24T14:15:22Z"}

Update Watched Store PATCH

Pause/resume the viewer's subscription and set its interval override.

Get Cluster Products GET

List the watchlist products in one active-layout cluster across ALL of the viewer's subscribed stores — ONE row per vendor (a product watched via N stores yields N rows), plus the cluster's ``cluster_label``/``cluster_color`` (``None`` when ``cluster_key`` isn't in the active layout). No subscription / no active layout → both ``None`` and empty data (count 0), never a 404.