Guide to Generating Publisher Reports With API

Vaida
Vaida
  • Updated

Reports provide you with accurate and relevant data that you can use to evaluate and improve your campaign setup.

With Adform Reporting Stats API, you can create a report with the dimensions and metrics that are most useful for evaluating the specific KPIs of your campaigns or inventory. To further customize your reports, Adform Reporting Stats API provides the option to filter, sort, and use paging for the data you want to retrieve.

Important

Reporting Stats API is an asynchronous API that can generate large reports for extensive use and doesn't have a row limit like the reports in the platform or spreadsheet files. This also means that you can't use this API to generate reports in real-time, because the report creation can take about one hour to complete. Calling the Reporting Stats API for real-time data can result in data delays and exceeded daily limit for requests.

If you want to retrieve your data to use with third-party aggregators such as dashboarding tools, you'll need an additional tool to store your asynchronously retrieved reporting data and use it for synchronous calls. Before using such a tool, contact Adform Support (technical@adform.com) to verify that you've selected a certified partner.

Prerequisites

To start working with Reporting Stats API, you need:

Note

If you don't have an OAuth client yet, follow the procedure in Get Authentication Credentials for Adform APIs to register one.

Create a Report

To create a report using Reporting Stats API, you must complete these steps:

  1. Retrieve metadata.

  2. Add filtering, sorting, and paging.

  3. Create a report operation.

  4. Check the report operation status.

  5. Retrieve the report.

The report creation workflow in Reporting Stats API looks like this:

Reporting_Stats_API_workflows_-_HQ.png

The report creation workflow includes only the specific steps needed to request and retrieve the report using Reporting Stats API endpoints. The first two steps provided in the procedure above are necessary to build and customize the report itself and must be done before requesting it. As such, the report creation workflow doesn't include these steps.

1. Retrieve Metadata

Before you can create or retrieve reports using Reporting Stats API, you need to decide on the specific dimensions and metrics that you want to include in your report. You can retrieve the lists of all metrics and dimensions available for you using the Metadata endpoints of Reporting Stats API.

Important

You can add a maximum of 14 dimensions and 12 metrics to one report.

Retrieve a List of Metrics

Metrics are measurements of user activity, such as impressions, clicks, or page views. To retrieve the list of all available metrics and their descriptions:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/seller/stats/metadata/metrics.

  5. Click Send.

Retrieve a List of Dimensions

Dimensions group metrics based on a common criteria, such as campaign or browser. To retrieve the list of all available dimensions and their descriptions:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v1/seller/stats/metadata/dimensions.

  5. Click Send.

2. Customize Your Reports

You can customize the data included in your report. With Reporting Stats API, you can add filters, sorting, and paging to the reports that you create.

Add Filters

You can use filters to define the specific data to include in the report. For example, you can add filters to your request to retrieve statistics for one line item or several placements. Filtering limits the rows that are included in the report, since the API checks each row against the filter and displays only the ones that match it.

Date is the only filter that must be included in all requests. If you don't add any other filters to your request, the API returns all possible rows for the specified time period.

Note

Not every filter parameter can be combined with particular metrics and dimensions. Currently, the only way to check if a combination is valid is to execute a query itself.

Available Filtering Parameters

Reporting Stats API offers a number of filters and filter parameters that you can use to specify the data you want to see in your reports. To retrieve the IDs for some of the filter parameters, you might need to use additional APIs.

Tip

The API doesn't limit the number of filters that you can add. However, keep in mind that overusing filters can result in no data included in your report.

You can add one or more filters from the table:

Filter Property

Parameter

Possible Values

Required

Example

date

Preset intervals (today, yesterday, pastSevenDays, pastThirtyDays, pastThirteenMonths)

Single

Yes

 
"date": "today"

Date period (from and to)

 
"date": { 
    "from": "2024-11-01", 
    "to": "2024-11-15" 
}

client

id

Multiple

No

 
"client": [12, 13]

or

"client": { 
    "id": [12, 13] 
}

name

 
"client": { 
    "name": ["name_12", "name_13"] 
}

campaign

id

Multiple

No

 
"campaign": [1222, 1333]

or

"campaign": { 
    "id": [1222, 1333] 
}

name

 
"campaign": { 
    "name": ["campaign_name_1222", "campaign_name_1333"] 
}

demandPartner

id

Multiple

No

 
"demandPartner": [4852, 44782]

or

"demandPartner": { 
    "id": [4852, 44782] 
}

name

 
"demandPartner": { 
    "name": ["demandPartner-01", "demandPartner-02"] 
}

lineItem

id

Multiple

No

 
"lineItem": [11456, 12312]

or

"lineItem": { 
    "id": [11456, 12312] 
}

name

 
"lineItem": { 
    "name": ["bp-01", "bp-top"] 
}

publisher

id

Multiple

No

 
"publisher": [246344, 33445]

or

"publisher": { 
    "id": [246344, 33445] 
}

name

 
"publisher": { 
    "name": ["publisher1", "publisher2"] 
}

placement

id

Multiple

No

 
"placement": [11456, 12312]

or

"placement": { 
    "id": [11456, 12312] 
}

name

 
"placement": { 
    "name": ["bp-01", "bp-top"] 
}

demandSource

id

Multiple

No

 
"demandSource": [11541, 11542]

or

"demandSource": { 
    "id": [11541, 11542] 
}

name

Multiple

 
"demandSource": { 
    "name": ["demandSource-01", "demandSource-02"] 
}

source

Single

 
"demandSource" : { 
    "source" : ["Real-Time"] 
}

or

"demandSource" : { 
    "source" : ["Direct"] 
}

buyer

id

Multiple

No

 
"buyer": [637849, 974620]

or

"buyer": { 
    "id": [637849, 974620] 
}

name

 
"buyer": { 
    "name": ["buyer1", "buyer2"] 
}

Example of Using Filters in a Request

{
   "metrics": [ ..... ],
   "dimensions": [ ..... ],
   "filter": {
      "date": "pastThirtyDays",
      "client": {
         "id": [12, 13, 14],
         "name": ["name_12", "name_13", "name_15"]
      },
      "campaign": {
         "id": [1222, 1333],
         "type": ["campaign"],
         "subtype": ["display", "RTB"]
      },
      "trackingPoint": "allConversions"
   }
}

Rules for Adding Filters

To successfully add filters to the reports that you want to create, keep in mind these filtering rules:

  • Filtering only works with exact matches for the filter parameters, such as names, IDs, or preset values.

  • Filtering is character and case-sensitive. For example, if you have a campaign labeled “December_2024 – Campaign”, filtering for “December 2024 campaign” will return no matches.

  • You can add multiple filters to your request. The API treats the comma between different filter conditions as an AND operator.

  • You can add multiple parameter values to the same filter in your request. The API treats the comma between the same filter values as an OR operator.

In this example, date, client, and campaign are filters with AND operator, and name_12 and name_13 are values with OR operator:

{
   "metrics": [ ..... ],
   "dimensions": [ ..... ],
   "filter": {
      "date": "pastThirtyDays",
      "client": {
         "name": ["name_12", "name_13"] // OR condition is applied within the same filter
condition values, either data for client name_12 or name_13 will be reported.
      }, // AND condition is applied for different filter parameters, both client name and 
campaign type data will be reported.
      "campaign": {
         "type": ["campaign"]
      }
   }, // Statistics will be returned for all campaigns of campaign type, for clients name_12 
or name_13 for the last 30 days period.
}

Add Sorting

You can use sorting to add an order direction — ascending or descending — to a metric or dimension and retrieve very specific data. For example, you can add sorting to find out which campaign performs better in terms of conversions.

Sorting is optional. If you don't add sorting to your request, the API sorts rows in an ascending order.

Available Sorting Parameters

Sorting Parameter

Possible Values

Required

Example

direction

Preset values (asc and desc)

No

 
"sort": {
      "dimension": "date",
      "direction": "desc"
}

Rules for Adding Sorting

To successfully sort the results that you want to see in the reports you create, keep in mind these sorting rules:

  • You can sort the results by one selected metric or by multiple dimensions.

  • You can sort only by a metric or dimensions that you're using in the query.

  • When you provide both dimensions and metrics for sorting, the API only applies metric sorting.

  • Sorting supports these directions: asc (ascending) and desc (descending). If you don’t provide a sorting direction, the API applies the default asc value.

  • For metrics, ascending order stands for numerical increasing order. For example, 100 > 101 > 102.

  • For dimensions, ascending order stands for alphabetical sorting. For example, for country dimension, Denmark > France > Germany > Italy.

Example of Using Sorting for Metrics

{
   "filter": { ... },
   "metrics": [ ... ],
   "paging": { ... },
   "sort": {
      "metric": { // query can be sorted by one metric in descending or ascending order
         "metric": "clicks",
         "direction": "desc"
      }
   }
}

Example of Using Sorting for Dimensions

{
   "filter": { ... },
   "metrics": [ ... ],
   "paging": { ... },
   "sort": {
      "dimensions": [ // alternatively, query can be sorted by multiple dimensions in descending or ascending order
         {
            "dimension": "campaign",
            "direction": "desc"
         },
         {
            "dimension": "lineItem",
            "direction": "asc"
         }
      ],
   }
}

Add Paging

You can use paging to define the starting point and the number of rows to include in the report. For example, you can add paging to retrieve 10 line items that have the highest number of impressions.

Paging is optional. If you don't add paging to your request, the API returns all rows starting from the first one.

Available Paging Parameters

Paging Parameter

Possible Values

Required

Example

offset

From 1 to unlimited

No

 
"paging": {
    "offset": 1,
}

limit

From 1 to unlimited

No

 
"paging": {
    "limit": 100
}

Rules for Adding Paging

To successfully add paging to the reports that you want to create, keep in mind these paging rules:

  • Both offset and limit parameters accept integer values.

  • Indexing of rows starts from 1, not 0. The default row index is 1.

  • By default, the number of rows per page is unlimited.

Example of Using Paging in a Request

{
   "filter": { ... },
   "metrics": [ ... ],
   "paging": {
      "offset": 1, // row index to start from
      "limit": 5 // number of rows to include in the response
   },
   "sort": [ {...}, {...} ]
}

3. Create a Report Operation

Once you decide what dimensions and metrics to include in your report and set up any filters, sorting, or paging, you can send a request to Reporting Stats API to generate a report. This request is called a report operation.

To create a new report operation, set up your API request body in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select POST method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/reports.

  5. Copy the example request body provided within that POST method in the List of API Operations section.

  6. In Postman, in the Body tab, paste the example request body.

  7. In Postman, replace the example values in request body with values relevant for your report. You can also add new parameters and values or remove any unnecessary ones. See the parameter list and the request body model for more information.

  8. Click Send.

If your request is successful, the response in the header will contain the relative location of the report operation:

HTTP/1.1 202 ACCEPTED
Content-Length: 0
Operation-Location: /v2/seller/stats/operations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx
Location: /v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy

If your request is not successful, refer to troubleshooting section to solve the issue.

4. Check the Report Operation Status

After you have sent a request to create a report operation and received the operation location, you can use it to track the status of the operation.

Important

It takes up to an hour to generate the report and update the report operation status.

To check the status of the report operation, use the GET method in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/operations/{id}.

    Note

    Replace the {id} part in the endpoint with the Operation-Location ID that was returned after creating a report operation.

  5. Click Send.

The returned operation status will have one of the following values:

  • notStarted: The report operation was created but is still waiting in the queue for the execution to begin.

  • running: The report operation is being executed.

  • succeeded: The report operation is completed and results are available at provided location.

  • failed: Indicates an internal server error. Create a new data operation to try again.

Check the status of the report operation using reasonable delays (at least 30 seconds) until operation status changes to either succeeded or failed state:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Location: /v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy
{
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
 "status": "succeeded",
 "createdAt": "2024-01-31T00:00:00.0000000Z",
 "lastActionAt": "2024-01-31T00:00:10.0000000Z",
 "location": "/v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy"
}

If your operation status changes to failed, create a new report operation and try again.

Note

A report operation expires and is removed from API responses in 24 hours after its status changes to succeeded or failed.

If you have more than one report operation creation request in process, you can track the status of all report operations at the same time.

To check the status of all report operations, use the GET method in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/operations.

  5. Click Send.

The response containing all report operations looks like this:

HTTP/1.1 200 OK
[
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
 "status": "notStarted",
 "createdAt": "2024-01-31T00:00:00.0000000Z",
 "lastActionAt": "2024-01-31T00:00:01.0000000Z",
 "location": "/v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy"
 },
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
 "status": "running",
 "createdAt": "2024-01-31T00:00:00.0000000Z",
 "lastActionAt": "2024-01-31T00:00:01.0000000Z",
 "location": "/v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy"
 },
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
 "status": "succeeded",
 "createdAt": "2024-01-31T00:00:00.0000000Z",
 "lastActionAt": "2024-01-31T00:00:01.0000000Z",
 "location": "/v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy"
 },
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
 "status": "failed",
 "createdAt": "2024-01-31T00:00:00.0000000Z",
 "lastActionAt": "2024-01-31T00:00:01.0000000Z",
 "location": "/v2/seller/stats/reports/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyy"
 }
]

5. Retrieve the Report

Once your report operation status changes to succeeded, the location provided in the response becomes active. You can use that location to retrieve your report.

To retrieve the created report, use the GET method in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select GET method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/reports/{id}.

    Note

    Replace the {id} part in the endpoint with the location ID that was returned after the report operation status changed to succeeded.

  5. Click Send.

If your request is successful, the response provides the requested report:

HTTP/1.1 200 OK
Transfer-Encoding: Chunked
{
 "reportData": {
 "columns": [
 { "key": "campaign" },
 { "key": "impressions" }
 ],
 "rows": [ "Test campaign", 777 ]
 }
}

If your request is not successful, refer to troubleshooting section to solve the issue.

Note

The requested report expires and can no longer be retrieved in 24 hours after it's generated.

Report data is transferred using HTTP chunked transfer encoding mechanism.

Delete a Report Operation or a Report

If you create a report operation for a report that you no longer need, you can cancel that report operation without waiting for its status to change.

To cancel a report operation, use the DELETE method in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select DELETE method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/operations/{id}.

    Note

    Replace the {id} part in the endpoint with the Operation-Location ID that was returned after creating a report operation.

  5. Click Send.

Note

If the report operation is already completed, canceling the report operation doesn't delete the generated report.

Similarly, if you create a report that you no longer need, you can delete it.

To delete a report, use the DELETE method in Postman:

  1. Open the Postman desktop app.

  2. Click Postman-icon.png to open a new tab.

  3. In the dropdown menu, select DELETE method.

  4. In the request URL field, enter https://api.adform.com/v2/seller/stats/reports/{id}.

    Note

    Replace the {id} part in the endpoint with the location ID that was returned after the report operation status changed to succeeded.

  5. Click Send.

Note

Deleting the generated report doesn't delete the related report operation.

Avoid Request Throttling

Reporting Stats API has a daily limit of 500 reports that, once reached, causes the server to stop processing report requests until the limit is reset.

Reporting Stats API also has these throttling rules:

If you reach the daily limit or send more requests than allowed by the throttling rules, the server returns an error response that indicates the exceeded throttling rule and the remaining time until the rule is reset:

HTTP/1.1 429
Throttle-Id: 781A52FDABDECE1BDD8881470B061E9E
Throttle-Retry-After: 49 // duration in seconds after which you can try again
Throttle-Limit-Exceeded: 10/60 // allowed request count per period in seconds
{
 "reason": "quotaLimitExceeded",
 "message": "Quota per Minute exceeded. Maximum admitted requests: 10 per Minute. Retry
in 49 seconds"
}

To learn more about how limitations and throttling rules apply in Adform APIs, see Learn About API Limits.

Troubleshoot Your Requests

If there are any issues with your request, Reporting Stats API will return an error response that includes an HTTP status code, a reason why the error occurred, and an explanation message for the error:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json; charset=utf-8
{
 "reason": "notFound",
 "message": "Operation with id '4aad43ac-5861-41ac-930e-710fb06bc770' not found."
}

To troubleshoot your issue, refer to the Recommendation column of the Error Responses table below.

Error Responses

Error Code

Reason

Message

Recommendation

400

emptyRequest

Empty request is provided.

You need to provide a valid JSON request. Fix the issue before trying again.

400

noDateFilter

Date filter has to be provided.

You need to provide the date filter. Fix the issue before trying again.

400

invalidDateRange

Only data for the last year (from today) can be reported.

You need to adjust the date filter values to include more recent data. Fix the issue before trying again.

400

invalidFilter

Filter has an invalid value.

You need to provide supported filters. Fix the issue before trying again.

400

invalidJSON

JSON request is not valid.

You need to provide a valid JSON request. Fix the issue before trying again.

400

invalidProperty

Property name has an invalid value.

You need to provide the correct property name to perform the operation on the specified entity. Fix the issue before trying again.

400

invalidPropertyType

Property value is of invalid data type.

You need to provide the correct property value to perform the operation on the specified entity. Fix the issue before trying again.

400

invalidPropertyValue

Value is invalid.

You need to provide the correct value to perform the operation on the specified entity. Fix the issue before trying again.

400

tooManyDimensions

Too many dimensions provided.

You need to provide no more than 14 dimensions. Fix the issue before trying again.

400

noMetrics

At least one metric has to be provided.

You need to provide at least one metric. Fix the issue before trying again.

400

tooManyMetrics

Too many metrics provided.

You need to provide no more than 12 metrics. Fix the issue before trying again.

400

invalidDimension

Dimension is invalid. Specify valid dimension name.

You need to provide the correct dimension name. Fix the issue before trying again.

400

invalidMetric

Metric is invalid. Specify valid metric name.

You need to provide the correct metric name. Fix the issue before trying again.

400

invalidMetricSpec

Metric spec is invalid. Specify valid metric spec name.

You need to provide the correct metric name. Fix the issue before trying again.

400

invalidSpecForMetric

Spec is not valid for a metric. Specify valid spec.

You need to provide the correct spec for a metric. Fix the issue before trying again.

400

invalidValueForSpec

Spec value is not valid for a spec. Specify valid spec value.

You need to provide the correct spec value for a metric. Fix the issue before trying again.

400

invalidBooleanValue

Value is invalid.

You need to provide the correct value to perform the operation on the specified entity. Fix the issue before trying again.

400

badSortingParameter

Value is invalid.

You need to provide the correct value to perform the operation on the specified entity. Fix the issue before trying again.

400

invalidPagingValue

Value is invalid.

You need to provide the correct value to perform the operation on the specified entity. Fix the issue before trying again.

400

invalidCombination

Combination of filters, dimensions, metrics and/or metric specs is not valid.

You need to provide a correct combination of filters, dimensions, and metrics. Fix the issue before trying again.

401

unauthenticated

Provided ticket value is invalid or has expired.

You need to provide new ticket information. Fix the issue before trying again.

401

unauthorized

Token is either invalid or expired.

You need to provide a correct token to perform the operation. Fix the issue before trying again.

403

unauthorized

User is not authorized to access Reporting Stats API. Contact account administrator.

You need to get sufficient permissions to perform the operation on the specified entity. Fix the issue before trying again.

403

unauthorizedDimensionOrMetric

Dimension(s) or metric(s) are unauthorized: {restrictions}.

You need Adform to grant you access to specific metrics or dimensions. Fix the issue before trying again.

403

insufficient_scope

Authorization token doesn't have scope required for this operation.

You need to provide an authorization token with a correct access scope to perform the operation. Fix the issue before trying again.

404

notFound

Requested resource doesn't exist.

You need to check that the provided path exists and that it's not expired. Fix the issue before trying again.

408

timeoutExceeded

Error might result during heavy load or for larger more complex requests. For larger requests consider requesting data for a shorter time period.

Consider requesting data for a shorter time period. Fix the issue before trying again.

429

quotaLimitExceeded

Request quota has been exceeded.

Retry after the provided time period in HTTP response headers: Throttle-Limit-Exceeded and Throttle-Retry-After.

500

An error with 500 HTTP status code might result during heavy load or for larger more complex requests.

Retry again in a few moments with increasing delay each time. For larger requests consider requesting data for a shorter time period. Contact Adform Support team (technical@adform.com) if the issue persists.

List of Reporting Stats API Parameters

These are the parameters that you must define when creating reports:

Parameter Name

Required or Optional

Description

Enum or Example Values

Type

dimensions

Optional

Dimensions group metrics based on a common criteria.

To see all available dimensions and their descriptions, follow the procedure in Dimensions section.

 
 "dimensions": [
    "date",
    "campaign",
    "placement"
 ]

Array

metrics

Required

Metrics are measurements of user activity.

To see all available metrics and their descriptions, follow the procedure in Metrics section.

 
"metrics": [
    {
      "metric": "impressions"
    },
    {
      "metric": "clicks"
    }
 ]

Array

metric

Required

metric is specified under metrics.

Metric defines the specific metric to include in the report.

 
"metric": "impressions"

String

filter

Required

Filter defines the specific data to include in the report.

See all available filtering parameters in Filters section.

 
"filter": {
    "date": {
      "from": "2024-11-03T16:41:45.3758941+00:00",
      "to": "2024-11-04T16:41:45.3758955+00:00"
    }
 }

Object

paging

Optional

Paging defines the starting point and the number of rows to include in the report.

See the available paging parameters in Paging section.

 
"paging": {
    "offset": 1,
    "limit": 100
 }

Object

includeRowCount

Optional

This parameter defines whether to include the total row count in the report.

 
"includeRowCount": true

Boolean

includeTotals

Optional

This parameter defines whether to include the totals for all requested metrics in the report.

 
"includeTotals": true

Boolean

sort

Optional

Sort defines the metric or dimension and its order direction to include in the report.

See the available sorting parameters in Sorting section.

 
"sort": [
    {
      "dimension": "date",
      "direction": "desc"
    },
    {
      "metric": "impressions",
      "direction": "asc"
    }
 ]

Object

consumerInfo

Optional

Consumer information defines the Reporting Stats API user's information, such as id and component.

Object

List of API Operations

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!