Retrieving results for a VAST tag

VAST analysis involves XML validation followed by video asset processing. A VAST tag can return different content on subsequent calls (variations), and each response can reference multiple video files. Retrieving the full scan results may require several API calls. This guide covers the steps involved.

Your case may be simpler

This guide walks through the most complex scenario. If your VAST tag has a single media file and no variations, you can skip the sections that don’t apply.

Prerequisites

You need a campaign with VAST creatives that have already been processed. Make sure you can see results in the Advalidation UI before trying to fetch them via the API.

Overview

The general flow is:

1. List creatives in your campaign from /campaigns/{campaignId}/creatives
2. Check for nbVariations on each creative
3. If nbVariations is present, use the variations route to get per-variation results (which includes media files)
4. If no nbVariations, fetch media files from /creatives/{creativeId}/media-files and get scan results for each
5. Fetch test results from /scans/{scanId} for every scan ID discovered

See the data model for the full hierarchy and decision logic.

Step 1: Find the campaign

Use /campaigns to retrieve your campaigns and find the one you need. Note the id — this is your campaignId.

{
  "data": [
    {
      "id": 25,
      "name": "My VAST campaign",
      "adspecId": 11
    }
  ]
}

Step 2: List campaign creatives

Use /campaigns/{campaignId}/creatives to list the creatives. The key fields are:

Field	Description
id	The creative ID
name	Creative name
nbVariations	Number of VAST variations (only present if the tag returns varying responses)
latestScanStatus.id	The scan ID for retrieving test results
latestScanStatus.nbIssues	Number of failing tests

{
  "data": [
    {
      "id": 56,
      "name": "Summer Sponsorship 30s",
      "latestScanStatus": {
        "id": 42,
        "processingStatus": "finished",
        "nbIssues": 7
      }
    },
    {
      "id": 53,
      "name": "Pre-roll Demo",
      "nbVariations": 4,
      "latestScanStatus": {
        "id": 61,
        "processingStatus": "finished",
        "nbIssues": 16
      }
    }
  ]
}

What you do next depends on whether the creative has nbVariations:

• Has nbVariations — the VAST tag returns different content on subsequent calls. The top-level scan (latestScanStatus.id) contains nbIssues as an aggregate count but no tests array. The actual test results live on the variations. Go to Step 3a: Variations.
• No nbVariations — the creative’s latestScanStatus.id gives you the VAST XML scan with test results. To get video file results, go to Step 3b: Media files.

Step 3a: Variations

When Advalidation detects that a VAST tag returns varying responses, it records each variation separately.

How variation detection works

When the VAST variations check is enabled in the ad specification, Advalidation downloads the VAST XML ten times and compares Ad IDs and Creative IDs across each load. The nbObservations field on each variation shows how many times it appeared in those ten loads.

1. List variations using /creatives/{creativeId}/variations:

{
  "data": [
    {
      "creativeId": 111,
      "label": "Variation A",
      "nbObservations": 4
    },
    {
      "creativeId": 222,
      "label": "Variation B",
      "nbObservations": 3
    }
  ]
}

Note the creativeId for each variation.

2. Get variation details using /creatives/{mainCreativeId}/variations/{variationCreativeId}. For example, /creatives/53/variations/111:

{
  "data": [
    {
      "id": 112,
      "parentId": 53,
      "sourceType": "vast-variation",
      "sourceTypeLabel": "VAST variation",
      "latestScanStatus": {
        "id": 118,
        "nbIssues": 1
      }
    },
    {
      "id": 113,
      "parentId": 53,
      "sourceType": "vast-child-video",
      "sourceTypeLabel": "VAST video media file",
      "latestScanStatus": {
        "id": 119,
        "nbIssues": 0
      }
    },
    {
      "id": 114,
      "parentId": 53,
      "sourceType": "vast-child-video",
      "sourceTypeLabel": "VAST video media file",
      "latestScanStatus": {
        "id": 120,
        "nbIssues": 0
      }
    }
  ]
}

The response includes:

• Items with sourceType: "vast-variation" — the VAST XML analysis for this variation
• Items with sourceType: "vast-child-video" — each video media file referenced in the tag

Use latestScanStatus.id from each item to fetch the test results.

Note

When using the variations route, media file results are included in the response. There is no need to call the /media-files endpoint separately.

Step 3b: Media files

For VAST creatives without variations, each media file referenced in the tag has its own scan. Fetch them using /creatives/{creativeId}/media-files:

{
  "data": [
    {
      "id": 444,
      "parentId": 56,
      "sourceType": "vast-child-video",
      "sourceTypeLabel": "VAST video media file",
      "latestScanStatus": {
        "id": 4444,
        "nbIssues": 0
      }
    },
    {
      "id": 555,
      "parentId": 56,
      "sourceType": "vast-child-video",
      "sourceTypeLabel": "VAST video media file",
      "latestScanStatus": {
        "id": 5555,
        "nbIssues": 0
      }
    }
  ]
}

Use latestScanStatus.id from each media file to fetch test results. You can also fetch results for the VAST XML itself using latestScanStatus.id from the parent creative (step 2).

Step 4: Fetch test results

Use /scans/{scanId} to get the test results for any scan ID obtained in the previous steps:

{
  "data": {
    "nbIssues": 2,
    "tests": [
      {
        "name": "Test_Video_Duration",
        "value": "15.04",
        "valueFormatted": "15 seconds",
        "valuePhrase": "Video track duration is 15 seconds (15.01). Audio track duration is 15 seconds (15.04).",
        "result": "fail",
        "attributes": [
          {
            "name": "Video_PlayTime",
            "description": "Duration of video in milliseconds",
            "value": 15.04
          }
        ]
      },
      {
        "name": "Test_Video_Codec",
        "value": "H264",
        "valueFormatted": "H264",
        "valuePhrase": "The video codec is H264.",
        "result": "pass",
        "attributes": [
          { "name": "Video_Codec", "description": "Video codec", "value": "H264" }
        ]
      }
    ]
  }
}

See The test array for a reference of all available tests and their fields.

Retrieving the ad specification

Each campaign has an associated ad specification that defines which tests are run and their expected values. You can retrieve it using the adspecId from the campaign object.

Use /ad-specifications/{adspecId}:

{
  "data": {
    "id": 1111,
    "name": "VAST",
    "isDefault": false,
    "isPublic": false,
    "tests": [
      {
        "name": "Test_Video_Resolution",
        "conditionsString": "320x240",
        "evaluationExpression": "..."
      },
      {
        "name": "Test_Video_AudioCodec",
        "conditionsString": "MP3 (MPEG Audio), AAC, WMA",
        "evaluationExpression": "..."
      }
    ]
  }
}

The conditionsString field shows the human-readable expected value for each test. The evaluationExpression field contains the evaluation logic in JsonLogic format — this is what Advalidation uses internally to determine pass or fail. Some tests (like Test_Video_VastCreativeCount) have no configurable parameters and will not include these fields.