Analysis Types
What each dataType returns, and what every response attribute means.
Get a brand analysis returns the analysis chosen
by dataType. The envelope is always the same — status, plus (when ok) the
fields brandId, dataType, datePreset, modifiedAt, and data. The
data field's shape is one of four, decided by dataType.
The endpoint's 200 response examples include a full, copy-ready JSON body for every
dataType— pick a type from the dropdown to see its exact response. This page explains what each shape and attribute means.
Analysis types
Pass exactly one dataType. Types marked (AI) require the brand's
hasAIReport: true (from List tracked brands).
| dataType | What it tells you | Response shape |
|---|---|---|
overview | Top-line summary: totals, media mix, average running days. | Summary |
ad_avg_lifespan | How long the brand's ads stay live, bucketed by duration. | Keyed metrics map |
platform_breakdown | Ad counts split by publisher platform. | Keyed metrics map |
copy_word_cloud | Most frequent words in the ad copy. | Word frequency list |
headline_diversity | Variety of headlines used. | Diversity rows |
cta_diversity | Variety of calls to action. | Diversity rows |
copy_diversity | Variety of ad copy. | Diversity rows |
landing_page_diversity | Variety of landing pages sent to. | Diversity rows |
color_palette (AI) | Dominant creative colours; each row's label is a hex colour. | Diversity rows |
ad_angle_diversity (AI) | Variety of ad angles / messaging approaches. | Diversity rows |
persona_diversity (AI) | Variety of target personas. | Diversity rows |
desire_diversity (AI) | Variety of customer desires addressed. | Diversity rows |
usp_diversity (AI) | Variety of unique selling propositions. | Diversity rows |
offer_diversity (AI) | Variety of offers / promotions. | Diversity rows |
funnel_breakdown_diversity (AI) | Variety of funnel stages targeted. | Diversity rows |
theme_diversity (AI) | Variety of creative themes. | Diversity rows |
objects_diversity (AI) | Variety of objects shown in creatives. | Diversity rows |
background_diversity (AI) | Variety of creative backgrounds. | Diversity rows |
emotion_diversity (AI) | Variety of emotional tones. | Diversity rows |
audio_hooks_diversity (AI) | Variety of audio hooks. | Diversity rows |
visual_hooks_diversity (AI) | Variety of visual hooks. | Diversity rows |
asset_type_diversity (AI) | Variety of asset types (image / video / etc.). | Diversity rows |
hook_tactic_diversity (AI) | Variety of hook tactics. | Diversity rows |
text_hook_diversity (AI) | Variety of text hooks. | Diversity rows |
headline_tactic_diversity (AI) | Variety of headline tactics. | Diversity rows |
seasonality_diversity (AI) | Variety across seasonal timing. | Diversity rows |
pacing_diversity (AI) | Variety of launch pacing. | Diversity rows |
Across every shape: dates are ISO 8601 (YYYY-MM-DD), all counts are whole
numbers, and a bucket/value with no ads is still returned (with zero counts) so
the set of keys is stable between calls.
Summary
Returned by overview. data is a single object describing the brand's whole
ad presence in the window.
| Attribute | Meaning |
|---|---|
totalCreatives | Total number of distinct ad creatives the brand ran in the window. |
avgRunningDays | Average number of days those creatives have stayed live. |
totalRunningDays | Combined running days across every creative (the sum of each ad's days live). |
mediaMix | Creatives broken down by format — image, video, carousel. For each format: active (currently live), inactive (stopped), total. |
{
"totalCreatives": 8624,
"avgRunningDays": 47.3,
"totalRunningDays": 408000,
"mediaMix": {
"image": { "active": 1200, "inactive": 2433, "total": 3633 },
"video": { "active": 870, "inactive": 4121, "total": 4991 },
"carousel": { "active": 0, "inactive": 0, "total": 0 }
}
}Diversity rows
Returned by every *_diversity type and by color_palette. data is a list
— one row per distinct value (cluster) of the attribute you asked about. For
example, persona_diversity returns one row per audience persona; cta_diversity
returns one row per call-to-action.
Every diversity type returns this exact structure — only the label content
(and whether clusterId is present) changes. Example labels per type:
| dataType | Example label values |
|---|---|
ad_angle_diversity | "Problem / solution", "Social proof", "Fear of missing out" |
persona_diversity | "Busy parents", "Budget shoppers" |
desire_diversity | "Save time", "Look younger" |
usp_diversity | "Clinically proven", "Free shipping" |
offer_diversity | "20% off first order", "Buy one get one" |
funnel_breakdown_diversity | "Awareness", "Consideration", "Conversion" |
theme_diversity | "Lifestyle", "Before / after" |
objects_diversity | "Product close-up", "Person holding product" |
background_diversity | "Outdoor / nature", "Studio / plain" |
emotion_diversity | "Joy", "Trust", "Urgency" |
audio_hooks_diversity | "Trending sound", "Voiceover question" |
visual_hooks_diversity | "Fast cuts", "Text on screen" |
asset_type_diversity | "UGC video", "Static image" |
hook_tactic_diversity | "Question hook", "Bold claim" |
text_hook_diversity | "Bold claim", "Statistic" |
headline_tactic_diversity | "Curiosity gap", "Direct benefit" |
headline_diversity | "No Boring Gifts!", "Save 20% Today" |
cta_diversity | "Shop now", "Learn more" |
copy_diversity | "Long-form story", "Short and punchy" |
landing_page_diversity | "/collections/bestsellers", "/products/gift-box" |
seasonality_diversity | "Holiday / Q4", "Summer" |
pacing_diversity | "Burst launch", "Always-on" |
color_palette | "#1a2b3c", "#e8c547" (a hex colour, not a name) |
Each row:
| Attribute | Meaning |
|---|---|
startDate / endDate | The date window this row covers. |
label | Human-readable name of the value this row represents (see the table above). |
clusterId | Stable id for an AI-detected group — use it to follow the same value across different time windows. Present only for AI types; basic types and color_palette omit it. |
…and inside data:
| Attribute | Meaning |
|---|---|
active / inactive / total | How many of the brand's ads fall under this value — currently live, stopped, and combined. |
video / image / carousel | The same ads, counted by creative format. |
longestAdDuration | The longest any single ad in this value has run, in days. |
avgRunningDays | Average days the ads in this value have run. |
uniqueInspirationCount | Number of distinct creatives in this value (duplicates removed). |
fbAdLibRank | The brand's standing in the Facebook Ad Library for this value: rank (1 = the most ads) out of totalAds. null if unranked. |
fbAdLibBestEverRank | The best (lowest-numbered) rank this value has ever reached. null if never ranked. |
fbAdLibRankMomentum | Change in rank since the previous period — negative means it moved up (improved), positive means it slipped. null if not comparable. |
reach | Estimated number of people who saw these ads, split by audience: total, male, female, unknown. Any value can be null when unavailable. |
reachMomentum | Change in reach versus the previous period (same breakdown). Positive = reach is growing. |
[
{
"startDate": "2026-05-01",
"endDate": "2026-05-31",
"label": "Problem / solution",
"clusterId": "01KSF5YW8FHGA2WAR0YXB6A1QB",
"data": {
"active": 12,
"inactive": 30,
"total": 42,
"video": 25,
"image": 17,
"carousel": 0,
"longestAdDuration": 180,
"avgRunningDays": 38.5,
"uniqueInspirationCount": 40,
"fbAdLibRank": { "rank": 3, "totalAds": 8624 },
"fbAdLibBestEverRank": 1,
"fbAdLibRankMomentum": -2,
"reach": { "total": 120000, "male": 54000, "female": 64000, "unknown": 2000 },
"reachMomentum": { "total": 15000, "male": 7000, "female": 7800, "unknown": 200 }
}
}
]Keyed metrics map
Returned by ad_avg_lifespan and platform_breakdown. data is an object
whose keys are a fixed set of buckets — every bucket is always present (zero-filled
if empty), so you can rely on the keys.
ad_avg_lifespan
Keys are lifespan buckets — ranges of days an ad has stayed live. 1-3 means
ads that ran between 1 and 3 days, 4-7 means 4 to 7 days, and so on, up to
360+ (ran 360 days or more). The full set is 1-3, 4-7, 8-14, 15-21,
22-30, 31-60, 61-90, 91-180, 181-360, 360+.
Each value tells you how many ads fall into that lifespan bucket:
| Attribute | Meaning |
|---|---|
total | Ads whose run length falls in this bucket. |
active | …of which are still live. |
inactive | …of which have stopped. |
startDate / endDate | The date window the counts cover. |
{
"1-3": { "total": 40, "active": 10, "inactive": 30, "startDate": "2026-05-01", "endDate": "2026-05-31" },
"4-7": { "total": 62, "active": 18, "inactive": 44, "startDate": "2026-05-01", "endDate": "2026-05-31" },
"8-14": { "total": 51, "active": 20, "inactive": 31, "startDate": "2026-05-01", "endDate": "2026-05-31" },
"360+": { "total": 4, "active": 4, "inactive": 0, "startDate": "2026-05-01", "endDate": "2026-05-31" }
}platform_breakdown
Keys are the publisher platforms the brand's ads run on: facebook,
instagram, audienceNetwork (Meta Audience Network — third-party apps and
sites), messenger, and threads.
Each value is the brand's ad count on that platform, by format:
| Attribute | Meaning |
|---|---|
video / image / carousel | Ads on this platform, counted by creative format. |
startDate / endDate | The date window the counts cover. |
{
"facebook": { "video": 25, "image": 17, "carousel": 0, "startDate": "2026-05-01", "endDate": "2026-05-31" },
"instagram": { "video": 18, "image": 12, "carousel": 0, "startDate": "2026-05-01", "endDate": "2026-05-31" },
"audienceNetwork": { "video": 2, "image": 1, "carousel": 0, "startDate": "2026-05-01", "endDate": "2026-05-31" }
}Word frequency list
Returned by copy_word_cloud. data is a list of the most common words in
the brand's ad copy, ordered most-frequent first.
| Attribute | Meaning |
|---|---|
word | A word found in the brand's ad copy. |
count | How many times it appeared across all the brand's ads in the window. |
[
{ "word": "free", "count": 312 },
{ "word": "sale", "count": 201 },
{ "word": "new", "count": 188 }
]