Insights Overview

The Adverteyes API provides assessments of creative performance. It provides:

1. Scoring: scores and diagnostics optimized for specific business objectives

2. Granular Metrics: comprehensive attention, emotion and content assessment for deep analysis

Together, this gives you the simplicity of actionable insights and detailed metrics for custom analysis.

Best audience in recommendations

When image or video predictions were requested with a non-empty detect_best_audience array, the result is also available from GET /v1/insights/recommendations/{file_id}. The response adds the same top-level best_audience object alongside the existing recommendations:

{
    "state": "processed",
    "model_versions": { "...": "existing model versions" },
    "data": [ "existing recommendation output" ],
    "request_id": "request-id",
    "best_audience": {
        "age_range": "18-29",
        "gender_distribution": "female"
    }
}

The field is omitted if the preceding predicted-reactions request did not ask to detect any audience dimension. This keeps the response backward compatible for current consumers.

If best-audience detection was requested but the Core audience artifact is not available yet, this endpoint returns state as processing. It returns processed with best_audience only after the requested audience values can be resolved. If the source prediction is missing the Core job ID needed to locate the artifact, the endpoint instead returns state as failed because the condition cannot be resolved by polling.

Scoring

How does Scoring work?

The API provides validated scores, each supported by diagnostics that explain performance. It simplifies decision-making by answering two critical questions:

• Will my creative drive in-market performance? Understand your creative’s predicted impact relative to benchmarks

• Why is my creative working? Identify the specific elements driving (or limiting) performance

Three Key Scores

1. Sales Impact Score

Purpose: Predict creative effectiveness for driving long-term sales

What it measures:

• Attention

• Emotional Engagement

• Performance Creative Benchmarks

Key signals:

• Strong Attention

• Strong Positive Emotion

• Overall Emotional Resonance

Use when: Your campaign objective is to drive long-term sales growth by creating strong, enduring memory structures

Example interpretation: A score of 56 means your creative is predicted to outperform 56% of ads in driving long-term sales impact.

---

2. Brand Awareness Score

Purpose: Predict creative effectiveness for driving brand recognition and recall

What it measures:

• Visual attention patterns

• Brand integration quality (timing and visibility)

• Performance vs. brand-building creative benchmarks

Key signals:

• Brand Introduced Early

• Maintains Brand Visibility

• Brand Shown While Viewers Are Engaged

Use when: Your campaign objective is to build brand awareness, recognition, or recall

Example interpretation: A score of 84 means your creative is predicted to outperform 84% of ads in driving brand awareness.

---

3. Interactions Score

Purpose: Predict creative effectiveness for driving engagement and short-term actions (swipes, clicks, likes)

What it measures:

• Visual attention patterns

• Exciting visual tone and atmosphere

• Moderate pacing that sustains interest

• Combined emotional reactions

• Performance creative benchmarks

Key signals:

• Creates Exciting Atmosphere

• Creates Dynamic Flow or Uses Measured Pacing (depending on format)

• Captures Above-Average Attention

Use when: Your campaign objective is to maximize engagement, swipes, clicks, or social interactions

Example interpretation: A score of 72 means your creative is predicted to outperform 72% of ads in driving interaction.

Diagnostics Library

Diagnostics are indicators that highlight specific creative elements contributing to or limiting performance.

Branding Diagnostics

Diagnostic	Description	Impact
Brand Shown While Viewers Are Engaged	Brand appears before average viewers lose interest.	Ensures branding reaches attentive audience
Brand Introduced Early	If your score is lower, branding appears later in your video than optimal, increasing the chance viewers disengage before brand recognition occurs.	Indicates whether branding in the video appears within the initial portion of the video (e.g., first 15 seconds).
Maintains Brand Visibility	If your score is lower, branding in your video may be under-represented on screen or appear inconsistently, reducing brand recognition.	Measures the proportion of screen space occupied by branding in the video, up to a defined maximum threshold.

Cognition Diagnostics

Diagnostic	Description	Impact
Uses Measured Pacing	Longer scene durations allow information processing.	Slower pacing aids comprehension and retention.
Creates Dynamic Flow	Quick scene changes maintain engagement and energy.	Fast pacing sustains attention and creates excitement.

Engagement Diagnostics

Diagnostic	Description	Impact
Captures Above-Average Attention	Video holds viewer attention better than typical content.	Ads with elevated levels of predicted attention have more headroom to influence lower-funnel outcomes.
Generates Strong Positive Emotions	Creates significant happiness peaks above normal levels.	Strong positive emotions drive brand favorability and sharing.
Triggers Meaningful Emotional Response	If your score is lower, your video elicits weaker emotional engagement compared to benchmark content.	Measures the degree to which the video elicits emotional engagement relative to established benchmarks.
Creates Exciting Atmosphere	If your score is lower, the visual style and execution may feel flat or subdued, limiting excitement and energy.	Assesses whether visual elements such as color, style, and expression contribute to a heightened sense of excitement.
Creates Calm Atmosphere	Visual style evokes serenity and tranquility.	Serene tones can build trust and emotional connection.
Balances Negative Emotional Triggers	Keeps contempt and disgust reactions at safe levels.	Avoiding negative emotions protects brand equity.

Persuasion Diagnostics

Diagnostic	Description	Impact
Maintains Attention During Message	No attention drop when main message is delivered.	Sustained attention ensures message comprehension.
Keeps Positive Mood During Message	Happiness levels maintained when message appears.	Positive emotional state improves message receptivity.
Delivers Clear Message	Confusion levels don’t rise during message delivery.	Clear messaging improves comprehension and recall.

Granular Metrics (Legacy)

All previously available metrics remain accessible through the original metrics endpoints. These include:

• Scene-by-scene attention and emotional metrics

• Scene detection and intelligence

• Visual element detection

• Custom metric combinations

When to Use Granular Metrics

Use granular metrics when you need to:

• Build custom scoring models

• Perform deep creative analysis

• Conduct research or testing beyond standard campaign goals

Accessing Granular Metrics

Granular metrics continue to be available through the existing /predicted-reactions endpoints. See the full metrics dictionary for complete documentation.