AdnovaDocs
Following Brands

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).

dataTypeWhat it tells youResponse shape
overviewTop-line summary: totals, media mix, average running days.Summary
ad_avg_lifespanHow long the brand's ads stay live, bucketed by duration.Keyed metrics map
platform_breakdownAd counts split by publisher platform.Keyed metrics map
copy_word_cloudMost frequent words in the ad copy.Word frequency list
headline_diversityVariety of headlines used.Diversity rows
cta_diversityVariety of calls to action.Diversity rows
copy_diversityVariety of ad copy.Diversity rows
landing_page_diversityVariety 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.

AttributeMeaning
totalCreativesTotal number of distinct ad creatives the brand ran in the window.
avgRunningDaysAverage number of days those creatives have stayed live.
totalRunningDaysCombined running days across every creative (the sum of each ad's days live).
mediaMixCreatives 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:

dataTypeExample 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:

AttributeMeaning
startDate / endDateThe date window this row covers.
labelHuman-readable name of the value this row represents (see the table above).
clusterIdStable 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:

AttributeMeaning
active / inactive / totalHow many of the brand's ads fall under this value — currently live, stopped, and combined.
video / image / carouselThe same ads, counted by creative format.
longestAdDurationThe longest any single ad in this value has run, in days.
avgRunningDaysAverage days the ads in this value have run.
uniqueInspirationCountNumber of distinct creatives in this value (duplicates removed).
fbAdLibRankThe brand's standing in the Facebook Ad Library for this value: rank (1 = the most ads) out of totalAds. null if unranked.
fbAdLibBestEverRankThe best (lowest-numbered) rank this value has ever reached. null if never ranked.
fbAdLibRankMomentumChange in rank since the previous period — negative means it moved up (improved), positive means it slipped. null if not comparable.
reachEstimated number of people who saw these ads, split by audience: total, male, female, unknown. Any value can be null when unavailable.
reachMomentumChange 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:

AttributeMeaning
totalAds whose run length falls in this bucket.
active…of which are still live.
inactive…of which have stopped.
startDate / endDateThe 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:

AttributeMeaning
video / image / carouselAds on this platform, counted by creative format.
startDate / endDateThe 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.

AttributeMeaning
wordA word found in the brand's ad copy.
countHow 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 }
]