Media Attention Report Service

This document describes how to access media attention reports generated by Viomba. The reports provide insights into the human attention performance of publishers and advertising inventory.

There are two ways to access the reports:

Fetch reports on demand via the Viomba Reporting API
Subscribe to scheduled report deliveries to your AWS S3 bucket

In both cases, commercial terms must be agreed with Viomba in advance.

Report format and structure

All reports are delivered as JSON Lines (JSONL) files. This format makes it efficient to process very large reports, as each row can be handled independently.

Each report consists of two parts:

Report header

The first line contains the report header, which describes the contents of the report. For example:

{"id":"benchmark","state":"READY","name":"Benchmark, split by device type and ad size","date":"2026-01-14","length":180,"dimensions":["deviceType","adSize"],"domains":"all","marketRegions":"all"}

The same header in a more readable format:

{
    "id": "benchmark",
    "state": "READY",
    "name": "Benchmark, split by device type and ad size",
    "date": "2026-01-14",
    "length": 180,
    "dimensions": [
        "deviceType",
        "adSize"
    ],
    "domains": "all",
    "marketRegions": "all"
}

Report rows

All subsequent lines contain individual report rows. For example:

{"deviceType":"DESKTOP","adSize":"160x600","seenPerc":0.31,"viewTime":2804}

Readable format:

{
  "deviceType": "DESKTOP",
  "adSize": "160x600",
  "seenPerc": 0.31,
  "viewTime": 2804
}

Report row structure

Each report row contains:

One or more dimensions defining where the row applies. Each report type has its own set of dimensions.
A set of metrics describing attention performance for that dimension combination.

If the report is a benchmark report, the metrics include only seenPerc and viewTime.

If the report is not a benchmark report but includes deviceType and adSize as dimensions, the metrics also include:

Comparisons against the corresponding benchmark
Ranking metrics (viewRank, seenRank) that describe performance relative to other rows with the same benchmark

Dimensions

Dimension	Description
`deviceType`	Device type the row applies to. Values are either `"MOBILE"` or `"DESKTOP"`.
`adSize`	CSS pixel size of the ad, formatted as `"{width}x{height}"`, for example `"320x200"`.
`domain`	Domain of the page, for example `"reuters.com"`. This may include a subdomain if relevant, such as `"dailystar.co.uk"`.
`urlPath`	A group of pages identified by the URL path prefix. The value includes everything up to the last `/` character. When multiple paths match a URL, the longest matching path must be used.
`adformPlacementId`	Placement ID issued by AdFrom, for example `"2212842"`
`xandrPlacementId`	Placement ID issued by Microsoft Advertising (formerly known as Xandr and AppNexus), for example `"31824410"`

Metrics

Metric	Appears in	Description
`seenPerc`	All reports	Ratio of seen ad impressions to viewable impressions. A float between 0 and 1.
`viewTime`	All reports	Average expected viewing time in milliseconds for impressions labeled as seen.
`viewRank`	Non-benchmark reports with `adSize` and `deviceType`	Fraction of other rows with the same `adSize` and `deviceType` that outperform this row by view time. Lower values indicate better performance.
`seenRank`	Non-benchmark reports with `adSize` and `deviceType`	Same as `viewRank`, but based on `seenPerc`.
`bmSeenPerc`	Non-benchmark reports with `adSize` and `deviceType`	Benchmark seen percentage for the corresponding `adSize` and `deviceType`.
`bmViewTime`	Non-benchmark reports with `adSize` and `deviceType`	Benchmark view time for the corresponding `adSize` and `deviceType`.
`bmRelSeen`	Non-benchmark reports with `adSize` and `deviceType`	Relative seen performance: `seenPerc / bmSeenPerc`.
`bmRelViewTime`	Non-benchmark reports with `adSize` and `deviceType`	Relative view-time performance: `viewTime / bmViewTime`.

Accessing reports

To access the reports, you need an API key issued by Viomba administration. The API key determines which parts of the dataset you are authorized to access.

All API requests must include the following HTTP header:

x-api-key: <your API key>

There are two ways to access the data:

Reporting API — retrieve reports on demand
S3 uploads — subscribe to scheduled deliveries to your AWS S3 bucket

Reporting API

The synchronous Reporting API provides two endpoints:

GET /api/report/list — list available reports
GET /api/report/:name/:dayLength/:date — fetch a specific report

GET /api/report/list

Returns a list of all currently available reports.

The response contains name, description, day length and breakdown dimensions for each currently available report.

For example:

[
    {
        "name": "benchmark",
        "description": "Benchmark, split by device type and ad size",
        "dayLength": 180,
        "dimensions": [
            "deviceType",
            "adSize"
        ]
    },
    {
        "name": "domain-performance",
        "description": "Domain performance, split by domain, device type and ad size",
        "dayLength": 180,
        "dimensions": [
            "domain",
            "deviceType",
            "adSize"
        ]
    },
    {
        "name": "url-path",
        "description": "URL path performance, split by URL path, device type and ad size",
        "dayLength": 180,
        "dimensions": [
            "urlPath",
            "deviceType",
            "adSize"
        ]
    }
]

GET /api/report/:name/:dayLength/:date

Retrieves a report for the given dayLength ending on date.

:name — report name (for example "url-path")
:dayLength — number of days included in the report
:date — end date of the report, in ISO format (YYYY-MM-DD)

The end-point reponds with the current state of the report generation, such as

{
    "state": "STARTED"
}

All the possible states are

STATE	Description
`STARTED`	The report was just requested
`PENDING`	The report is queued for generation, but not yet started
`RUNNING`	The report is being generated
`ERROR`	There was an error generating the report. This is a permanent state for the report.
`READY`	The report has been generated successfully. This is a permanent state for the report.

If the state is "READY", the report content is returned as well:


{
    "id": "domain-performance",
    "state": "READY",
    "name": "Domain performance, split by domain, device type and ad size",
    "date": "2026-01-14",
    "length": 180,
    "dimensions": [
        "domain",
        "deviceType",
        "adSize"
    ],
    "domains": "example.com,example2.com",
    "marketRegions": "all"
}
{
    "domain": "example.com",
    "deviceType": "DESKTOP",
    "adSize": "160x600",
    "seenPerc": 0.65,
    "viewTime": 833,
    "viewRank": 1,
    "seenRank": 0,
    "bmSeenPerc": 0.616,
    "bmViewTime": 1646,
    "bmRelSeen": 1.0552,
    "bmRelViewTime": 0.5061
},
...

S3 uploads

S3 uploads allow reports to be delivered automatically to your AWS S3 bucket on a recurring schedule.

S3 configuration can be set up either:

via the API
By sending the configuration details to Viomba administration via email

The available end-points for managing the S3 subscriptions via the API are listed below. All the end-points respond with the same response, which is the updated effective list of active S3 configurations.

GET /api/s3/subscriptions

Just returns the current S3 subscription configurations for your account.

For example:

[
    {
        "id": 2,
        "nextDeliveryDate": "2026-01-19",
        "frequency": "WEEKLY",
        "s3config": {
            "bucket": "my-bucket",
            "region": "eu-north-1",
            "accessKeyId": "1234",
            "secretAccessKey": "567890"
        },
        "reports": [
            {
                "report": "benchmark",
                "dayLength": 180
            }
        ]
    },
    {
        "id": 3,
        "nextDeliveryDate": "2026-01-19",
        "frequency": "DAILY",
        "s3config": {
            "bucket": "my-bucket",
            "region": "eu-north-1",
            "accessKeyId": "1234",
            "secretAccessKey": "567890"
        },
        "reports": [
            {
                "report": "domain-performance",
                "dayLength": 180
            },
            {
                "report": "url-path",
                "dayLength": 180
            }
        ]
    }
]

Each configuration object in the array is defined as

Property	Type	Description
`id`	number	The ID of the configration. The id is to reference the configuration when updating or stopping it
`nextDeliveryDate`	string	ISO-date of the next scheduled delivery
`frequency`	string	The frequency of the deliveries, either `"DAILY"`, `"WEEKLY"` or `"MONTHLY"`
`s3Config`	object	The S3 configuration to use when the subscription files are delivered. The properties of the object contain `bucket`: the name of the S3 bucket, `region`: The AWS region of the bucket, `accessKeyId` and `secretAccessKey`: credentials to use.
`reports`	array of objects	Reports included in the delivery. Each object has two properties, `report`: the name of the report, and `dayLength` the data length

POST /api/s3/subscriptions

Creates a new S3 subscription configuration for your account. The subscription object is defined in GET /s3/subscriptions (see earlier)

For example:

{
    "frequency": "WEEKLY",
    "s3config": {
        "accessKeyId": "1234",
        "secretAccessKey": "567890",
        "region": "eu-north-1",
        "bucket": "my-bucket"  
    },
    "reports": [
        {
            "report": "benchmark",
            "dayLength": 180
        },
        {
            "report": "url-path",
            "dayLength": 180
        }
    ]
}

The response is the new updated list of S3 configurations.

PUT /api/s3/subscriptions/:id

Updates an existing S3 subscription confirmation on your account. The configuration is identified by the path parameter :id

For example:

PUT /s3/subscriptions/2
{
    "frequency": "MONTHLY",
    "s3config": {
        "accessKeyId": "1234",
        "secretAccessKey": "567890",
        "region": "eu-north-1",
        "bucket": "my-bucket"  
    },
    "reports": [
        {
            "report": "benchmark",
            "dayLength": 180
        }
    ]
}

The response is the new updated list of S3 configurations.

POST /api/s3/subscriptions/:id/stop

Stops a S3 configuration. The configuration is identified by the path parameter :id.

POST /s3/subscriptions/2/stop

The response is the new updated list of S3 configurations.

# Media Attention Report Service

# Report format and structure

# Report header

# Report rows

# Report row structure

# Dimensions

# Metrics

# Accessing reports

# Reporting API

# GET /api/report/list

# GET /api/report/:name/:dayLength/:date

# S3 uploads

# GET /api/s3/subscriptions

# POST /api/s3/subscriptions

# PUT /api/s3/subscriptions/:id

# POST /api/s3/subscriptions/:id/stop

Media Attention Report Service

Report format and structure

Report header

Report rows

Report row structure

Dimensions

Metrics

Accessing reports

Reporting API

GET /api/report/list

GET /api/report/:name/:dayLength/:date

S3 uploads

GET /api/s3/subscriptions

POST /api/s3/subscriptions

PUT /api/s3/subscriptions/:id

POST /api/s3/subscriptions/:id/stop