Engage Header Bidding API
Overview
The Engage Reports API provides RESTful interfaces for interacting with the Header Bidding Reports product.
The API is structured around core entities:
- Publisher: A publisher account
- Report: Analytics entities to retrieve metrics
Support Contact
For questions, issues, or feature requests, contact hb@outbrain.com.
API URL
The base URL for all API endpoints is:
https://api.outbrain.com/engage/v2/Authentication
Obtaining a token is the first step toward using the Engage API. The token must be included in all further requests using the HTTP header OB-TOKEN-V1.
Token Lifecycle
- Tokens are valid for 30 days. Expired tokens cannot access the Engage API.
- Generating a new token does not invalidate older tokens.
- When an account password or email is changed, all previously generated tokens are revoked and a new token must be generated.
How to Obtain a Token
Tokens are obtained by making a request to the login endpoint using Basic Authentication.
- Endpoint:
https://api.outbrain.com/engage/v1/login - Authentication Header Format:
Authorization: BASIC BASE64(YOUR_OUTBRAIN_USERNAME:YOUR_OUTBRAIN_PASSWORD)
All communication with the Engage API uses HTTPS, ensuring credentials are secure.
cURL Example
curl -u YOUR_OUTBRAIN_USERNAME:YOUR_OUTBRAIN_PASSWORD https://api.outbrain.com/engage/v1/loginUse the -v flag to view the Authorization HTTP header in the response.
Token Management Recommendation
Store an active token for use in all requests and periodically update it (every 30 days or less) to stay within authentication limits.
Rate Limits
| Endpoint / Level | Limit | Window |
|---|---|---|
Authentication requests (/login) | 2 requests | Per hour per user |
| Reporting API | 30 requests | Per minute per publisher |
When rate limits are exceeded, the API returns HTTP status code 429 (Too Many Requests).
Users
Users represent individual account access to Teads services and to the publisher dashboard. Users have permissions to one or more Publisher accounts.
Users cannot be managed via this API and must be created with the help of your Teads representative.
Reports
Report endpoints allow you to retrieve metrics at various levels of granularity.
Performance Metric Latency
Performance reports have a 2–4 hour delay. Performance metrics for the current day are partial.
Response Structure
All reporting endpoints share a common response structure:
| Property | Type | Description |
|---|---|---|
items | Array | Report items for the specific report type. |
totalItems | Number | Count of total results after filtering. |
metricsSums | Object | Aggregated metrics for the returned set of data after filtering. |
Filter Parameters
| Operator | Description | Example |
|---|---|---|
:eq: | Equal | /reports/headerBidding?filter=revenue:eq:2000 |
:gt: | Greater than | /reports/headerBidding?filter=revenue:gt:300 |
:lt: | Less than | /reports/headerBidding?filter=revenue:lt:890 |
:between: | Between | /reports/headerBidding?filter=revenue:between:20,900 |
:in: | In (list) | /reports/headerBidding?filter=placement:in:2089,84984,38984 |
:not_in: | Not in (list) | /reports/headerBidding?filter=placement:not_in:2089,8466 |
:contains: | Contains (string) | /reports/headerBidding?filter=placement:contains:ar |
:not_contains: | Not contains (string) | /reports/headerBidding?filter=placement:not_contains:ar |
Chaining Filters
Use semicolon (;) to chain multiple filters:
filter=revenue:gt:2000;placement:in:234,657Note: Nesting of Boolean operators is not currently supported.
ReportItems Fields
| Property | Type | Description | Breakdown Availability |
|---|---|---|---|
day | String | Date in format yyyyMMdd | Optional breakdown |
revenue | Number | Publisher revenue in USD | All |
impressions | Number | Total number of impressions served | All |
clicks | Number | Total number of clicks | All |
ctr | Number | Average CTR: (clicks / impressions) * 100 | All |
rpm | Number | Revenue per thousand impressions: (revenue / impressions) * 1000 | All |
country | String | Country entity | Optional breakdown |
device | String | User device | Optional breakdown |
tagId | String | TagID / placement entity provided by publisher | Optional breakdown |
environment | String | App or Web | Optional breakdown |
domain | String | Page domain | Optional breakdown |
channel | String | Media type | Optional breakdown |
Request Structure / Parameters
| Parameter | Type | Required | Details |
|---|---|---|---|
entityId | String | Yes | External ID of the entity (publisher/group). Contact your account manager for this ID. |
entityType | String | Yes | Entity type. This API supports only PUBLISHER. |
fromDate | String | Yes | Start date (yyyyMMdd). |
toDate | String | Yes | End date (yyyyMMdd). |
limit | Number | No | Max results to return. Default: 500, Max: 10000. |
offset | Number | No | Ordinal index of first result to retrieve. Default: 0. |
sort | String | No | Sorting field. Default: revenue. |
order | String | No | Sorting order (asc or desc). Default: desc. |
filter | String | No | Filter expression string. |
breakdowns | Array | No | Aggregation entities. Default: day. Max: 4. |
currencyCode | String | No | Revenue currency code. Default: USD. |
Breakdowns
| Breakdown | Description | Example |
|---|---|---|
day | Day entity | /reports/headerBidding?breakdowns=day |
device | Device entity | /reports/headerBidding?breakdowns=device |
tagId | TagId / placement entity | /reports/headerBidding?breakdowns=tagId |
environment | Environment entity | /reports/headerBidding?breakdowns=environment |
domain | Domain entity | /reports/headerBidding?breakdowns=domain |
channel | Channel entity | /reports/headerBidding?breakdowns=channel |
country | Country entity | /reports/headerBidding?breakdowns=country |
Chaining Breakdowns
Use comma (,) to chain multiple breakdowns (up to 4 supported):
breakdowns=day,tagIdError Handling
The API follows RESTful conventions for HTTP status codes:
| 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 lacks permissions. |
403 | Forbidden | Access denied. |
404 | Not Found | Resource was not found. |
429 | Too Many Requests | Rate limit exceeded. |
504 | Gateway Timeout | Request timed out. |
When an error status code is returned, a JSON response describes the error:
{
"moreInfo": "getReport",
"errorMessage": "access denied"
}Troubleshooting
- Community Support: Post in the Outbrain Engage API Google Group.
- Trace Header: Include the
x-traceidheader from the response in your inquiry to help our support team trace and resolve the issue quickly.