Engage Reports API - Header Bidding
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: A variety of analytics entities to retrieve metrics
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 Validity
- Tokens are valid for 30 days
- Expired tokens cannot access the Engage API
- Generating a new token does not invalidate older tokens
- When a user 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.
Example using curl:
curl -u YOUR_OUTBRAIN_USERNAME:YOUR_OUTBRAIN_PASSWORD https://api.outbrain.com/engage/v1/login
Use 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. Since tokens are valid for 30 days, update the token at least every 30 days.
Rate Limits
The following rate limits are enforced:
| Endpoint/Level | Limit | Unit |
|---|---|---|
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 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.
Reports
Report endpoints allow you to retrieve metrics at various levels of granularity.
Note: Performance reports have a 2–4 hours delay. 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 | ReportItems for the specific report type |
| totalItems | Number | Count of total results after filtering | |
| metricsSums | Metrics | Aggregated metrics for the set of data returned after filtering | Structure varies per report type |
Filter Parameters
The following table describes the basic filter operators:
| 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,657
Note: Nesting of Boolean operators is not currently supported.
ReportItems Fields
ReportItems contain aggregation entities and traffic metric fields:
| Property | Type | Semantic | Comments |
|---|---|---|---|
| day | String | Date in format "yyyyMMdd" | Optional breakdown |
| revenue | Number | Publisher revenue | |
| impressions | Number | Total number of impressions served | |
| clicks | Number | Total number of clicks | |
| ctr | Number | Average Click Through Rate (clicks / impressions served) | |
| rpm | Number | Revenue per thousand impressions: (revenue / impressions) * 1000 | |
| country | String | Country | Optional breakdown |
| device | String | User device | Optional breakdown |
| tagId | String | TagID as provided by the publisher | Optional breakdown (placement entity) |
| environment | String | App or Web | Optional breakdown |
| domain | String | Page domain | Optional breakdown |
| channel | String | Media type | Optional breakdown |
Request Structure / Parameters
| Parameter | Type | Semantic | Details |
|---|---|---|---|
| entityId | String | External ID of the entity (publisher/group) | Required. Contact your Teads account manager for your external ID. |
| entityType | String | Entity type | This API supports only PUBLISHER entity type |
| fromDate | String | Start date of results | Format: "yyyyMMdd". Required. |
| toDate | String | End date of results | Format: "yyyyMMdd". Required. |
| limit | Number | Maximal number of results to return | Optional. Default: 500 |
| offset | Number | Ordinal number of first result to retrieve | Optional. Default: 0 |
| sort | String | Sorting field (metric or entity name) | Optional. Default: revenue |
| order | String | Sorting order of results | Optional. Default: descending. Allowed values: asc or desc |
| filter | String | Filtering based on filter guidelines | Optional. |
| breakdowns | Array of Strings | Aggregation entities for results | Optional. Default: day. Maximum 4 breakdowns supported. |
| currencyCode | String | Revenue currency code | Optional. Default: USD |
Pagination
Use the offset and limit query parameters to create an iterative pagination process:
- First page (1000 results): Set
offset=0(or use default) andlimit=1000 - Second page: Set
offset=1000andlimit=1000 - Third page: Set
offset=2000andlimit=1000 - Continue as needed
Maximum results: The Teads API allows a maximum of 10,000 results to be requested. For large result sets, pagination should always be used.
Breakdowns
The following table describes the aggregation options (report breakdowns):
| Operator | 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
breakdowns=day,brandName
Maximum: A maximum of 4 breakdowns are supported.
Error Handling
The API follows RESTful conventions for HTTP status codes:
| 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 the 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. |
When the API returns an error status code (400, 401, 403, 404, 429), it includes a JSON response describing the error:
{
"moreInfo": "getReport",
"errorMessage": "access denied"
}
Troubleshooting
If you experience any issues or difficulties:
- Post to Google Group: https://groups.google.com/forum/#!forum/outbrain-engageapi
- Include the AMPLIFY-REQUEST-ID header from the returned response in your post. This unique request ID allows support to identify your request and reply more quickly and efficiently.