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)

info

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/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 (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

warning

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.

note

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,657

Note: 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,tagId

---

Error 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

1. Community Support: Post in the Outbrain Engage API Google Group.
2. Trace Header: Include the x-traceid header from the response in your inquiry to help our support team trace and resolve the issue quickly.