Engage API V2 (Outbrain)
Overview
The Engage API V2 describes the interfaces for interacting with the Teads Engage Reports product. More information about Engage can be found on the Outbrain publisher help site.
The API is RESTful and structured into the following core entities and operations:
| Entity | Function |
|---|---|
| Publishers | Read |
| Widgets | Read |
| Nativeapps | Read |
| Countries | Read |
| Timezones | Read |
| Report | Function |
|---|---|
| Outbrain | Read |
HTTP requests follow RESTful conventions using HTTP methods to determine the type of action:
| HTTP Method | Action |
|---|---|
| GET | Retrieve a resource or a list of resources |
HTTP Status Code Replies
| HTTP Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | The request was successful |
| 400 | Bad Request | The request could not be understood or was missing required parameters |
| 401 | Unauthorized | Authentication failed or user doesn't have permissions for requested operation |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Resource was not found |
| 429 | Too Many Requests | Request exceeded rate limits |
| 504 | Gateway Timeout | Request timeout |
API URL
The base URL for all API endpoints is:
https://api.outbrain.com/engage/v2
What's New in V2?
V2 introduces enhanced security by protecting your publisher ID, making it a hashed string (in both Request and Response). Please contact your Teads account manager to acquire this ID.
The limit parameter has a maximum of 10,000 requested items. If you are using a limit greater than 10,000, adjust your request to avoid failure. This change improves performance and stability for all users. Pagination is encouraged if you expect to reach this limit.
Migration Example
Migrate requests from V1 to V2:
V1: api.outbrain.com/engage/v1/reports/outbrain/publishers/publisherId..
V2: api.outbrain.com/engage/v2/reports/outbrain?entityId=extPublisherId..
Authentication
Obtaining a Token
Obtaining a token is your first step toward using the Engage API. You must include it in all further requests using the HTTP header OB-TOKEN-V1.
Tokens are valid for 30 days. You will not be able to access the Engage API using an expired token. You can generate as many tokens as you wish; generating a new token does not invalidate older tokens. When a user password or email is changed, all tokens generated prior to the change are revoked and a new token must be generated.
Token Request
This is the only API transaction in which you need to supply your Teads credentials using Basic Authentication.
The HTTP request should include a header:
- Name:
Authorization - Value:
BASIC BASE-64-ENC(YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD)
Since all communication to the Engage API uses HTTPS, your credentials are safe.
cURL Example
curl -u YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD https://api.outbrain.com/engage/v2/login
Add -v to see the Authorization HTTP header in the output.
Rate Limits
The following rate limits are enforced at different API levels:
- Authentication requests (
/login): Limited to 2 requests per hour per user - Reporting API: Each publisher is limited to 30 requests per minute for the entire reporting API
In any case of rate limit violation, the response status will be 429 (Too Many Requests).
Token Management Recommendation
Given the limitation on /login requests, the recommended way to manage tokens is to:
- Store an active token to be used in all requests
- Periodically update it (every 30 days or less)
This avoids hitting the 2-requests-per-hour limit on the /login endpoint.
Users
Users represent a single person's access to Teads services and to the site my.outbrain.com. Users have permissions to one or more Publisher accounts.
Note: Users cannot be managed via this API and must be created with the help of your Teads contact.
Publisher Lookups
Publishers cannot be created via the API and must be created via a Teads Account Manager.
Publishers Collection
Retrieve all Publishers associated with the current user (as identified by the token in the OB-TOKEN-V1 HTTP header).
Widgets Collection
Retrieve all Widgets associated with the publisher with external ID {id} (as identified by the token in the OB-TOKEN-V1 HTTP header).
Nativeapps Collection
Retrieve all native apps associated with the publisher with external ID {id} (as identified by the token in the OB-TOKEN-V1 HTTP header).
General Lookups
Countries Collection
Retrieve list of all Countries.
Timezones Collection
Retrieve list of all Timezones.
Reports
Overview
Report endpoints allow you to retrieve metrics at various levels of granularity.
Note: Performance reports have a 2-4 hours delay; therefore, performance metrics for the current day are partial.
Response Structure
All reporting endpoints share a common response structure:
| Property | Type | Semantic | Comments |
|---|---|---|---|
| items | Array | Metrics of the entities returned | OutbrainReportItems |
| totalItems | Number | Count of the total results after filtering | |
| metricsSums | OutbrainReportItems | Aggregated metrics for the set of data returned after filtering |
Filter Parameters
The following table describes the basic filter operators:
| Operator | Description | Example |
|---|---|---|
:eq: | Equal (numeric) | outbrain?filter=revenue:eq:2000 |
:gt: | Greater than (numeric) | outbrain?filter=organicClicks:gt:300 |
:lt: | Less than (numeric) | outbrain?filter=paidClicks:lt:890 |
:between: | Between (numeric) | outbrain?filter=revenue:between:20,900 |
:in: | In (list) | outbrain?filter=widget:in:2089,84984,38984 |
:not_in: | Not in (list) | outbrain?filter=widget:not_in:2089,8466 |
:contains: | Contains (string) | outbrain?filter=referrer:contains:ar |
:not_contains: | Not contains (string) | outbrain?filter=referrer:not_contains:ar |
You can chain filters with ;, for example: filter=revenue:gt:2000;widget:in:234,657.
Note: Nesting of Boolean operators is not supported currently.
OutbrainReportItems Fields
Object containing aggregation entities and traffic metric fields.
| Property | Type | Semantic | Comments |
|---|---|---|---|
| day | String | Date format "yyyyMMdd" | Optional breakdown |
| month | String | Date format "yyyyMM" | Optional breakdown |
| platform | Object | Platform entity | Optional breakdown |
| referrer | Object | Referrer entity | Optional breakdown |
| country | Object | Country entity | Optional breakdown |
| section | Object | Section entity | Optional breakdown |
| widget | Object | Widget entity | Optional breakdown |
| doc | Object | Document entity | Optional breakdown |
| partnerApp | Object | Partner app entity | Optional breakdown |
| paidPvs | Number | Total number of pageviews with at least one Teads paid link | Not available on widget breakdown |
| totalPvs | Number | Total number of pageviews with at least one Teads link | Not available on widget breakdown |
| paidReqs | Number | Total number of paid widget requests | Available only on widget breakdown |
| totalReqs | Number | Total number of widget requests | Available only on widget breakdown |
| revenue | Number | Revenue | |
| rpmByPvs | Number | (Revenue / paidPvs)*1000 | |
| reqsRpm | Number | (Revenue / paidReqs)*1000 | |
| paidClicks | Number | Total number of paid clicks | |
| organicClicks | Number | Total number of organic clicks | |
| totalClicks | Number | Total number of clicks | |
| paidCtrByPvs | Number | The average CTR (Click Through Rate), (Paid clicks / paidPvs)*100 | |
| totalCtrByPvs | Number | The average CTR (Click Through Rate), (Total clicks / totalPvs)*100 | |
| reqsPaidCtr | Number | The average CTR (Click Through Rate), (Paid clicks / paidReqs)*100 | |
| reqsTotalCtr | Number | The average CTR (Click Through Rate), (Total clicks / totalReqs)*100 | |
| organicPvs | Number | Total number of pageviews with at least one Teads organic link | Not available on widget breakdown |
| organicReqs | Number | Total number of organic widget requests | Available only on widget breakdown |
| organicCtrByPvs | Number | The average CTR (Click Through Rate), (Organic clicks / organicPvs)*100 | |
| reqsOrganicCtr | Number | The average CTR (Click Through Rate), (Organic clicks / organicReqs)*100 | |
| videoRevenue | Number | Net revenue generated from Video | |
| videoPlays | Number | Number of Video Plays | |
| viewabilityRate | Number | Percent of total requests with widget in-view, (Widget exposed / Widget served)*100 | |
| paidViewabilityRate | Number | Percent of paid requests with paid widget in-view, (Paid widget exposed / Paid widget served)*100 | |
| organicViewabilityRate | Number | Percent of organic requests with organic widget in-view, (Organic widget exposed / Organic widget served)*100 | |
| viewableCtr | Number | Total clicks divided by total in-view requests, (Total clicks / [totalReqs * viewabilityRate])*100 | |
| viewableOrganicCtr | Number | Number of organic clicks divided by in-view organic requests, (Organic clicks / [organicReqs * organicViewabilityRate])*100 | |
| viewablePaidCtr | Number | Number of paid clicks divided by in-view paid requests, (Paid clicks / [paidReqs * paidViewabilityRate])*100 | |
| viewableRpm | Number | Revenue per one thousand Teads paid in-view requests, (Revenue / [paidReqs * paidViewabilityRate])*1000 | |
| optInRateByReqs | Number | Consent Rate: % of traffic where users gave consent or not required based on their geo location, (Total opt in reqs / Total reqs) x 100 | By Requests. Not supported on doc breakdown |
| optInRateByPvs | Number | Consent Rate: % of traffic where users gave consent or not required based on their geo location, (Total opt in PVs / Total PVs) x 100 | By Page Views. Not supported on doc breakdown |
Widget Entity
| Name | Value | Example |
|---|---|---|
| value | Widget custom name (jsId) | Article footer desktop (AR_1) |
| id | Widget numeric ID | 100 |
| customValue | Widget's custom value | Desktop article |
| jsId | Widget jsID | AR_1 |
Request Structure / Parameters
| Parameter | Type | Semantic | Details |
|---|---|---|---|
| entityId | String | Set the external ID of the entity (publisher/group) | Required. Contact your Teads account manager for your external ID. |
| fromDate | String | The start date-time of results | Format "yyyyMMdd" |
| toDate | String | The end date-time of results | Format "yyyyMMdd" |
| limit | Number | Maximal number of results to return | Optional, default: 500, maximum: 10,000 |
| offset | Number | The ordinal number of the first result to be retrieved | Optional, default: 0 |
| sort | String | Set the sorting field (metric or entity) of the results | Optional, default: revenue |
| order | String | Set the sorting order of the results | Optional, default: descending; allowed values: asc or desc |
| filter | String | Set filtering based on filter guidelines | Optional |
| breakdowns | Array of Strings | Set aggregation entities of results | Optional, default: day |
| currencyCode | String | Set the revenue currency code | Optional, default: USD |
| decDigits | Number | Number of decimal places for revenue | Optional, default: 2; allowed values: 0-6 |
Pagination
The offset and limit query parameters are useful for creating an iterative pagination process.
Example:
- First page (1000 results): Set
offset=0(or use default) andlimit=1000 - Second page: Set
offset=1000andlimit=1000 - Third page: Set
offset=2000andlimit=1000
The Engage API allows a maximum of 10,000 results to be requested in a single call. Pagination should always be considered as the solution for retrieving large result sets.
Breakdowns
The following table describes the aggregation options (report breakdowns = chosen entities).
| Breakdown | Description | Example |
|---|---|---|
| day | Day entity | /reports/outbrain?breakdowns=day&entityId={entityId} |
| month | Month entity | /reports/outbrain?breakdowns=month&entityId={entityId} |
| platform | Platform entity | /reports/outbrain?breakdowns=platform&entityId={entityId} |
| referrer | Referrer entity | /reports/outbrain?breakdowns=referrer&entityId={entityId} |
| country | Country entity | /reports/outbrain?breakdowns=country&entityId={entityId} |
| section | Section entity | /reports/outbrain?breakdowns=section&entityId={entityId} |
| widget | Widget entity | /reports/outbrain?breakdowns=widget&entityId={entityId} |
| doc | Document entity | /reports/outbrain?breakdowns=doc&entityId={entityId} |
| partnerApp | Partner app entity | /reports/outbrain?breakdowns=partnerApp&entityId={entityId} |
You can chain breakdowns with ,, for example: breakdowns=day,widget.
Maximum number of breakdowns supported: 4
Unsupported Breakdown Combinations
The following breakdown combinations are not supported:
- Day/month
- Referrer/country
- Referrer/doc
- Country/doc
Note: Doc level breakdown is available only for the last year.
Error Handling
When the API returns a status code indicating an error (400, 401, 403, 404, 429), it includes JSON describing the error.
Error Response Example
{
"moreInfo": "getWidgets",
"errorMessage": "access denied"
}
Troubleshooting
If you experience any issues or difficulties, please post a new topic in the Engage API Google Group.
When posting, please attach the x-traceid header from the returned response. This header allows support to identify your unique request and helps them to reply quicker and more efficiently.
For questions, issues, and feature requests, join the Google Group: https://groups.google.com/forum/#!forum/engageapi