POST /api/v1/batch/scan

Validate up to 50 HTML5 ad creatives in a single request. Returns individual reports and aggregated summary statistics.

Overview

The batch scan endpoint processes multiple creative ZIP files in one API call. Each file is validated independently against 40+ checks including IAB compliance, clickTag detection, and performance metrics. Results include both per-file reports and an aggregate summary.

Files are processed sequentially on the server to manage memory usage. Each successfully processed creative consumes one scan credit. Files that fail validation (e.g. missing index.html) do not consume credits.

Plan requirement: Available with API Business ($899/month) or API Enterprise (custom pricing) plans only.

Request

Endpoint

POST https://adloom.io/api/v1/batch/scan

Authentication

Include your API key in the request header:

X-API-Key: adl_your_api_key_here

Content type

Requests must use multipart/form-data encoding.

Parameters

files (required)

Type: File[] (multiple ZIP files)

One or more ZIP files containing HTML5 ad creatives. Maximum 50 files per request. The field name can be files, files[], or file (repeated).

target_platform (optional)

Type: String

Target ad platform applied to all files in the batch. If omitted, the default platform on the API key is used, or generic detection.

Example requests

Using curl

curl -X POST https://adloom.io/api/v1/batch/scan \
  -H "X-API-Key: adl_your_api_key_here" \
  -F "files=@banner-300x250.zip" \
  -F "files=@banner-728x90.zip" \
  -F "files=@banner-160x600.zip" \
  -F "target_platform=cm360"

Using JavaScript/Node.js

const fs = require('fs');

const formData = new FormData();
formData.append('files', fs.createReadStream('banner-300x250.zip'));
formData.append('files', fs.createReadStream('banner-728x90.zip'));
formData.append('files', fs.createReadStream('banner-160x600.zip'));
formData.append('target_platform', 'cm360');

const response = await fetch('https://adloom.io/api/v1/batch/scan', {
  method: 'POST',
  headers: { 'X-API-Key': 'adl_your_api_key_here' },
  body: formData
});

const data = await response.json();
console.log(data.summary);
// { total: 3, succeeded: 3, failed: 0, averageScore: 87 }

Response

Status code

200 OK on success (even if individual files failed)

Response fields

summary

Type: Object

Aggregate statistics for the entire batch:

total (number): Total files submitted

succeeded (number): Files successfully processed

failed (number): Files that failed to process

averageScore (number): Average score across all successful scans

results

Type: Array

Array of per-file results, one for each uploaded file. Each result contains:

filename (string): Original filename

success (boolean): Whether this file was processed successfully

error (string, optional): Error message if the file failed

report (object, optional): Full scan report (same structure as the single /scan endpoint response)

usage

Type: Object

Quota information with used (total scans used this month) and limit (monthly limit)

Example response

{
  "success": true,
  "summary": {
    "total": 3,
    "succeeded": 3,
    "failed": 0,
    "averageScore": 87
  },
  "results": [
    {
      "filename": "banner-300x250.zip",
      "success": true,
      "report": {
        "targetPlatform": "cm360",
        "dimensions": { "width": 300, "height": 250 },
        "fileSize": 145.2,
        "entryFile": "index.html",
        "score": 92,
        "clicktag": { "detected": true, "type": "cm360", "variable": "clickTag" },
        "tests": [ ... ],
        "categories": [ ... ],
        "meta": { "fileCount": 5, "hasBackupImage": true, "hasMetaAdSize": true, "usesHttps": true }
      }
    },
    {
      "filename": "banner-728x90.zip",
      "success": true,
      "report": { ... }
    },
    {
      "filename": "banner-160x600.zip",
      "success": true,
      "report": { ... }
    }
  ],
  "usage": { "used": 503, "limit": 10000 },
  "durationMs": 1245
}

Quota and billing

The endpoint checks your remaining quota before processing. If you do not have enough credits for the full batch, the request is rejected with a 429 status and a breakdown of your remaining quota.

Only successfully processed files consume credits. If a file is not a valid ZIP or has no index.html, no credit is deducted for that file.

Error handling

400 Bad request

No files provided or more than 50 files submitted

401 Unauthorized

Invalid or missing API key

403 Forbidden

Your plan does not support batch operations

429 Too many requests

Insufficient quota for the requested batch size

Next steps

POST /api/v1/batch/fix: Batch scan and fix creatives POST /api/v1/scan: Single creative scan API overview