Get Media

This endpoint returns the details of a media.

A media identifier must be provided in the URL of the request. The endpoint returns the media prediction results.

Images

For images, this endpoint will return the results of the latest prediction. An example of the image prediction results payload is shown here.

Videos

For videos this endpoint can be used for polling and checking ont he video prediction status.

After triggering the prediction, the endpoint will show the video prediction status as started and no prediction results will be returned.

{
    "media_id": "cf98f5d0-0f1d-45d1-a718-2ec30e47c5c3",
    "name": "test-api-reaeneo6co",
    "status": "started",
    "type": "video",
    "aoi_status": "unspecified",
    "results": {},
    "metrics": {},
    "created_at": "2025-10-27T10:42:56Z",
    "updated_at": "2025-10-27T10:43:36Z"
}

Since FRT metrics rely on a different model, this model may return the results faster, so it's possible to start seeing some of the prediction results, while the status still showing as started. This is because the other prediction metrics are still not ready. It can look like this:

{
    "media_id": "cf98f5d0-0f1d-45d1-a718-2ec30e47c5c3",
    "name": "test-api-reaeneo6co",
    "status": "started",
    "type": "video",
    "aoi_status": "unspecified",
    "results": {
        "frt_frame_metrics": "https://files.neuronsinc.com/media_frt_metrics.json"
    },
    "metrics": {
        "engagement_new": 59.82097432497457,
        "engagement_new_start": 49.751782217228595,
        "engagement_new_end": 53.535068658041666,
        "memory": 67.23993655809444,
        "memory_start": 79.422116571275,
        "memory_end": 45.96465080110347,
        "intent": 58.228892737548165,
        "intent_start": 64.8852371981359,
        "intent_end": 47.83007575740604,
        "trust": 61.53557246540469,
        "trust_start": 64.59517482869735,
        "trust_end": 60.17279595088593,
        "avoidance": 24.6908416069659,
        "avoidance_start": 20.18989383332671,
        "avoidance_end": 28.09362502079395
    },
    "created_at": "2025-10-27T10:42:56Z",
    "updated_at": "2025-10-27T10:44:14Z"
}

Example of a successful response

When a video prediction is completed, the status field will show as done and all prediction metrics and heatmaps will be visible in the results.

NOTE: The assets will only be available under the URL's for a maximum period of 5 minutes, so make sure to download them before they expire.

{
    "media_id": "cf98f5d0-0f1d-45d1-a718-2ec30e47c5c3",
    "name": "test-api-reaeneo6co",
    "status": "done",
    "type": "video",
    "aoi_status": "unspecified",
    "results": {
        "heat": "https://files.neuronsinc.com/nv-production/media_nvai_heat.mp4",
        "fog": "https://files.neuronsinc.com/nv-production/media_nvai_fog.mp4",
        "formatted": "https://files.neuronsinc.com/nv-production/media_nvai_formatted.mp4",
        "metrics": "https://files.neuronsinc.com/nv-production/media_nvai_metrics.json",
        "frt_frame_metrics": "https://files.neuronsinc.com/nv-production/media_frt_metrics.json",
        "brand_detection": "https://files.neuronsinc.com/nv-production/media_brand_detection.json",
        "brand_detection_metrics": "https://files.neuronsinc.com/nv-production/media_brand_detection_metrics.json"
    },
    "metrics": {
        "cognitive_demand": 66.9217452956358,
        "focus": 47.74784716196852,
        "focus_first_two": 53.86280407268669,
        "focus_last_two": 64.74491052452959,
        "engagement_new": 59.82097432497457,
        "engagement_new_start": 49.751782217228595,
        "engagement_new_end": 53.535068658041666,
        "memory": 67.23993655809444,
        "memory_start": 79.422116571275,
        "memory_end": 45.96465080110347,
        "intent": 58.228892737548165,
        "intent_start": 64.8852371981359,
        "intent_end": 47.83007575740604,
        "trust": 61.53557246540469,
        "trust_start": 64.59517482869735,
        "trust_end": 60.17279595088593,
        "avoidance": 24.6908416069659,
        "avoidance_start": 20.18989383332671,
        "avoidance_end": 28.09362502079395
    },
    "created_at": "2025-10-27T10:42:56Z",
    "updated_at": "2025-10-27T10:48:18Z"
}

Note that when the aoi_status field still shows as unspecified, this means that no video AOIs have been calculated. You can run video AOI detection or calculate static video AOIs and, once the AOI calculation is finished the aoi_status field will show as done and an additional field aoi_scores will be visible.

{
    "media_id": "cf98f5d0-0f1d-45d1-a718-2ec30e47c5c3",
    "name": "test-api-reaeneo6co",
    "status": "done",
    "type": "video",
    "aoi_status": "done",
    "results": {
        "heat": "https://files.neuronsinc.com/nv-production/media_nvai_heat.mp4",
        "fog": "https://files.neuronsinc.com/nv-production/media_nvai_fog.mp4",
        "formatted": "https://files.neuronsinc.com/nv-production/media_nvai_formatted.mp4",
        "metrics": "https://files.neuronsinc.com/nv-production/media_nvai_metrics.json",
        "frt_frame_metrics": "https://files.neuronsinc.com/nv-production/media_frt_metrics.json",
        "brand_detection": "https://files.neuronsinc.com/nv-production/media_brand_detection.json",
        "brand_detection_metrics": "https://files.neuronsinc.com/nv-production/media_brand_detection_metrics.json",
        "aoi_scores": "https://files.neuronsinc.com/nv-production/media_aoi_metrics.csv"
    },
    "metrics": {
        "cognitive_demand": 66.9217452956358,
        "focus": 47.74784716196852,
        "focus_first_two": 53.86280407268669,
        "focus_last_two": 64.74491052452959,
        "engagement_new": 59.82097432497457,
        "engagement_new_start": 49.751782217228595,
        "engagement_new_end": 53.535068658041666,
        "memory": 67.23993655809444,
        "memory_start": 79.422116571275,
        "memory_end": 45.96465080110347,
        "intent": 58.228892737548165,
        "intent_start": 64.8852371981359,
        "intent_end": 47.83007575740604,
        "trust": 61.53557246540469,
        "trust_start": 64.59517482869735,
        "trust_end": 60.17279595088593,
        "avoidance": 24.6908416069659,
        "avoidance_start": 20.18989383332671,
        "avoidance_end": 28.09362502079395
    },
    "created_at": "2025-10-27T10:42:56Z",
    "updated_at": "2025-10-27T10:56:35Z"
}

Video prediction results

Below there's a brief explanation of each field in the video prediction results:

media_id: The unique identifier, which can be used to query the media.
name: The name of the video file. This is autogenerated.
status: The prediction status. If status is done then results should be visible in the response.
type: The type of media (image or video).

The heat maps are stored as video assets (with an expiry, as explained above), and links can be find under results:

heat: This is the attention heat map.
fog: This is the attention fog map.
formatted: This is the original video (no heat map).
metrics: A JSON document with the frame-by-frame video legacy metrics results: attention (focus), cognitive demand and clarity.
frt_frame_metrics: A JSON document with the frame-by-frame video FRT metrics results: intent, engagement, trust, avoidance and memory.
brand_detection: A JSON document with the frame-by-frame AOI attention metric results.
brand_detection_metrics: A JSON document with the overall AOI attention metrics.
aoi_scores: A CSV document with the overall AOI attention metrics.

Metrics (find out what each metric means in this article):

cognitive_demand: The value for cognitive demand (in percentage).
focus: The value for total attention (in percentage).
focus_first_two: The value for attention during the first two seconds (in percentage).
focus_last_two: The value for attention during the final two seconds (in percentage).
engagement_new: The value for the brand new engagement metric (in percentage).
engagement_new_start: The value for the brand new engagement metric during the first two seconds (in percentage).
engagement_new_end: The value for the brand new engagement metric during the last two seconds (in percentage).
memory: The value for the brand new memory metric (in percentage).
memory_start: The value for the brand new memory metric during the first two seconds (in percentage).
memory_end: The value for the brand new memory metric during the last two seconds (in percentage).
intent: The value for the brand new intent metric (in percentage). Based on association words like Explore, Consider, Choose, Try, Recommend and Buy, this behavioural metric provides a gauge for how likely the viewers of the creative are to act upon the ads message. It signals the consumer’s likelihood to engage, recommend or purchase. The Intent metric translates into strong consideration, conversion or advocacy as an initial reaction to the creative.
intent_start: The value for the brand new intent metric during the first two seconds (in percentage).
intent_end: The value for the brand new intent metric during the last two seconds (in percentage).
trust: The value for the brand new trust metric (in percentage). Based on association words like Trustworthy, Honest and Sincere this cognitive metric gives an assessment of the level of trust built by the creative. As the other FRT Metrics (like Engagement) it measures gut reaction of to what extend the asset fosters trust and a sense of authentic message. This can drive brand equity, retention and loyalty as well as influencing consideration.
trust_start: The value for the brand new trust metric during the first two seconds (in percentage).
trust_end: The value for the brand new trust metric during the last two seconds (in percentage).
avoidance: The value for the brand new avoidance metric (in percentage). Based on the association words Boring and Annoying this metric shows for the first time a gut reaction of negative sentiment to the creative. It measures the extent to which a creative creates disinterest, discontent or friction. At the core of the metric is the assessment of avoidance-related motivation and behaviour and is a strong indicator of dropoff, negative association and acts against brand building and lift.
avoidance_start: The value for the brand new avoidance metric during the first two seconds (in percentage).
avoidance_end: The value for the brand new avoidance metric during the last two seconds(in percentage).