Performance Reporting

There are a multitude of reporting endpoints that allow you to retrieve metrics at various levels of granularity.

Note: All performance reports have a 10-30 minutes delay, therefore performance metrics that include the current day are partial.

Rate Limits

Each marketer is limited to 30 requests per minute for the entire performance reporting API. In case of rate limit violation the response status will be 429 (Too Many Requests).

As of April 12, 2021 performance reporting is limited to a history of 3 years per data request.

Response structure

All reporting endpoints share a common response structure, defined below:

Metrics

Object containing performance metric fields. The spend field and all derived fields are based on the marketer currency, available in each of the marketer's budget object (see Budget).

Conversion Metrics

Object containing performance metrics for conversion pixels.

In order to use conversion metric fields in sorting and filtering, the field name should be formatted as follows: conversionMetrics/{conversionField}/{conversionName}, where {conversionField} is the conversion metric field name, and {conversionName} is the conversion pixel name with all spaces replaced by '-'.

For example, the conversionRate field of a conversion pixel with the name "registration" is represented by conversionMetrics/conversionRate/registration. The cpa field of a conversion pixel with the name "full event" is represented by conversionMetrics/cpa/full-event.

Apple SKAdNetwork conversions

Apple SKAdNetwork conversions have limited data and thus will not appear the same as standard Outbrain conversions: All Apple Conversions will be written at the time the data is received from the Apple servers. Apple Conversions will not be included in Conversion totals. This Data is available in Campaign, Month, Date, Day of Week, Publisher and Platform (under Mobile, iOS and in-app by default) reports.

To include Apple SKAdNetwork conversions metrics in the response add the following parameter to your request: includeAppleSkAdNetworkData=true.

The following properties will be added to the response's Metrics object.

Video (click-to-watch) metrics

Video metrics are not available for Interest report.

Note: The general measure of clicks for a click-to-watch campaign indicates the number of unique video plays across the requested date range. This measure should not be confused with clicksOnVideo which indicates clicks happening after the video started playing.

To include video metrics in the response add the following parameter to your request: includeVideoStats=true.

The following properties will be added to the response's Metrics object.

Request Structure

All reporting endpoints share common request parameters, defined below:

###Sort Parameters The sort parameter contains a sort direction charachter, '+' for ascending and '-' for descending, followed by the name of the performance or metadata field to sort by. The list of specific fields relevant for each endpoint is given in its definition.

For example, '-spend' will sort results by spend value descending.

###Filter Parameters The following table describes the basic filter operators. The first example will filter campaigns leaving only those whose name is 'Campaign X'.

You can chain filters with the and or or operators, for example clicks+gt+99+and+cpc+lt+0.7.

Nesting of Boolean operators is not supported currently.

The following table describes string comparison functions available in filtering. The first example will filter campaigns leaving only those whose name contains the string 'USA'.

Full day of data

Return the last day for which the data in perfromance reports is complete. Result fields:

Endpoints

• Retrieve last day of full data — GET /reports/fullDay

Data Freshness

Return the last timestamps for which the data in performance reports is available. Result fields:

Endpoints

• Retrieve data freshness — GET /reports/dataFreshness

Marketers

The API in this sub-section allows retrieving primary account marketers data with performance statistics.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve marketers with performance statistics for a Primary Account — GET /reports/accounts/{primaryAccountId}/marketers

Campaigns

The API in this sub-section allows retrieving marketer campaigns data with performance statistics.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve campaigns with performance statistics for a Marketer — GET /reports/marketers/{id}/campaigns

Promoted Content

The API in this sub-section allows retrieving performance statistics by promoted link at different levels: marketer, budget, campaign and promoted link.

This new endpoint also supports promoted links that are creative format: CAROUSEL and APP_INSTALL, these were previously excluded from the original Content endpoint. Please note that this endpoint is replacing the previous Content endpoint which will be removed by October 2022.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Special request parameters

Endpoints

• Retrieve promoted content links performance statistics for a Marketer — GET /reports/marketers/{id}/promotedContent

Periodic

The API in this sub-section allows retrieving performance statistics by periodic breakdown at different levels: marketer, budget, campaign and promoted link.

Special request parameters

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve periodic performance statistics for a Marketer — GET /reports/marketers/{id}/periodic

Periodic by campaign

A special endpoint for retrieving periodic data by campaign breakdown. Now supports all breakdowns: daily, weekly, monthly, hourOfDay, dayOfWeek and dayOfWeekByHour.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have periodic results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by periodic breakdown — GET /reports/marketers/{id}/campaigns/periodic

Periodic by campaign hourly

A special endpoint for retrieving periodic data by campaign in hourly breakdown.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have periodic results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by periodic hourly breakdown — GET /reports/marketers/{id}/campaigns/periodicHourly

Periodic by campaign minutely

A special endpoint for retrieving periodic data by campaign in minutely breakdown.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have periodic results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by periodic minutely breakdown — GET /reports/marketers/{id}/campaigns/periodicMinutely

Periodic content

A special endpoint for retrieving periodic data by promoted link breakdown for a given campaign.

Note: The response structure defers from other performance responses.

The reponse contains only promoted links that have periodic results given the offset and limit, in the following two objects:

Endpoints

• Retrieve periodic performance statistics by promoted link for a campaign — GET /reports/marketers/{id}/campaigns/{campaignId}/periodicContent

Periodic content hourly

An endpoint for retrieving periodic data by promoted link for a given campaign in an hourly breakdown - limited to last 48 hours.

Note: The response structure defers from other performance responses.

The reponse contains only promoted links that have periodic results given the offset and limit, in the following two objects:

Endpoints

• Retrieve hourly periodic performance statistics by promoted link for a campaign — GET /reports/marketers/{id}/campaigns/{campaignId}/periodicContentHourly

Publishers

Publisher: A content site that displays Outbrain recommendations on which your promoted content appeared.

The API in this sub-section allows retrieving marketer performance statistics with breakdown by publisher with publishers that are already blocked at the marketer or campaign level.

Result Fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve performance statistics for a Marketer by publisher — GET /reports/marketers/{id}/publishers

Publishers by campaign

A special endpoint for retrieving publishers data by campaign breakdown.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have publishers results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by publisher — GET /reports/marketers/{id}/campaigns/publishers

Sections

Section: A specific content section within the publisher's site such as sports, business etc.

The API in this sub-section allows retrieving marketer performance statistics with breakdown by section with sections that are already blocked at the marketer or campaign level.

Note: Sections with less than 1 click or less than 10 impressions will not show up in the results.

Result Fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve performance statistics for a Marketer by section — GET /reports/marketers/{id}/sections

Sections by campaign

A special endpoint for retrieving sections data by campaign breakdown.

Note: The response structure defers from other performance responses.

Note 2: Sections with less than 1 click or less than 10 impressions will not show up in the results.

The reponse contains only campaigns that have sections results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by section — GET /reports/marketers/{id}/campaigns/sections

Sections by date

Endpoint for retrieving sections data by date in a daily breakdown.

Note: The response structure defers from other performance responses.

Note2: Sections with less than 1 click or less than 10 impressions will not show up in the results.

Endpoints

• Retrieve performance statistics for all marketer sections by dates — GET /reports/marketers/{id}/sections/date

Sections by date hourly

Endpoint for retrieving sections data by date in a hourly breakdown (last 48 hours).

Note: The response structure defers from other performance responses.

Note2: Sections with less than 1 click or less than 10 impressions will not show up in the results.

Endpoints

• Retrieve performance statistics for all marketer sections by dates hourly — GET /reports/marketers/{id}/sections/dateHourly

Sections by date minutely

Endpoint for retrieving sections data by date in a minutely breakdown (last 360 minutes).

Note: The response structure defers from other performance responses.

Note2: Sections with less than 1 click or less than 10 impressions will not show up in the results.

Endpoints

• Retrieve performance statistics for all marketer sections by dates minutely — GET /reports/marketers/{id}/sections/dateMinutely

Platforms

The API in this sub-section allows retrieving performance statistics by platform at different levels: marketer, budget, and campaign.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve performance statistics for a Marketer by platform — GET /reports/marketers/{id}/platforms

Platforms by campaign

A special endpoint for retrieving platforms data by campaign breakdown.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have platforms results given the offset and limit, in the following two objects:

Endpoints

• Retrieve performance statistics for all marketer campaigns by platform — GET /reports/marketers/{id}/campaigns/platforms

Geo

The API in this sub-section allows retrieving performance statistics by geographic breakdown at different levels: country, region, and DMA.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Special request parameters

Endpoints

• Retrieve geo performance statistics for a Marketer — GET /reports/marketers/{id}/geo

Geo by campaign

A special endpoint for retrieving geo data by campaign breakdown.

Note: The response structure defers from other performance responses.

The reponse contains only campaigns that have geo results given the offset and limit, in the following two objects:

Special request parameters

Endpoints

• Retrieve performance statistics for all marketer campaigns by geo — GET /reports/marketers/{id}/campaigns/geo

Interests

The API in this sub-section allows retrieving performance statistics by interest at different levels: marketer and campaign.

In all other performance reporting endpoints each user action (impression, click or conversion) is attributed to a single entity, for example campaign, section or region.

Interests behave differently, since users can have multiple interests in their Outbrain Interest Profile and therefore data repeats between interests. For example, a user may be interested in both health and politics and so an impression, click or conversion will be attributed to both interests. As a result, the sum of the total interests reported does not represent the actual sum of action taken.

Therefore, the summary and summaryFiltered metrics are not included in the response of interest performance reports.

Result fields

Metrics in metrics, metadata in a metadata object containing the following fields:

Endpoints

• Retrieve performance statistics for a Marketer by interest — GET /reports/marketers/{id}/interests