Engage API V2 (Outbrain)

Overview

The Engage API V2 provides RESTful interfaces for interacting with the Teads Engage Reports product. For more information, visit the Outbrain publisher help center.

The API is structured around the following core entities and operations:

Entity / Report	Supported Operations
Publishers	Read (GET)
Widgets	Read (GET)
Nativeapps	Read (GET)
Countries	Read (GET)
Timezones	Read (GET)
Outbrain Report	Read (GET)

HTTP Methods

Method	Action
GET	Retrieve a resource or list of resources.

HTTP Status Code Replies

Status Code	Meaning	Description
200	OK	The request was successful.
400	Bad Request	The request was malformed or missing required parameters.
401	Unauthorized	Authentication failed or user lacks permissions.
403	Forbidden	Access denied.
404	Not Found	Requested resource was not found.
429	Too Many Requests	Rate limit exceeded.
504	Gateway Timeout	Request timed out.

---

API URL

The base URL for all API endpoints is:

https://api.outbrain.com/engage/v2

What's New in V2?

Enhanced Security & Limits

• Hashed Publisher ID: V2 secures your account by using a hashed string for your publisher ID in both request parameters and response bodies. Contact your Teads account manager to receive this ID.
• Request Limit (10,000 max): The limit parameter now has a ceiling of 10,000 items. If your requests require more items, implement pagination using offset and limit.

Migration Example

# V1
GET https://api.outbrain.com/engage/v1/reports/outbrain/publishers/publisherId...

# V2
GET https://api.outbrain.com/engage/v2/reports/outbrain?entityId=extPublisherId...

---

Authentication

Obtaining a Token

You must include an authentication token in all API requests using the HTTP header OB-TOKEN-V1.

Token Lifecycle

• Tokens are valid for 30 days. Expired tokens cannot access the API.
• Generating a new token does not invalidate previously generated active tokens.
• When an account password or email is changed, all prior tokens are revoked immediately.

Token Request

The /login endpoint is the only transaction requiring Basic Authentication.

Include an HTTP header:

• Header Name: Authorization
• Value: BASIC BASE-64-ENC(YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD)

info

All communication with the Engage API uses HTTPS, keeping credentials safe.

cURL Example

curl -u YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD https://api.outbrain.com/engage/v2/login

Add -v to inspect the Authorization HTTP header in the output.

Token Management Recommendation

Given the rate limit of 2 requests/hour on the /login endpoint, store and reuse an active token, refreshing it once every 30 days or less.

---

Rate Limits

Scope	Limit	Window
Authentication (/login)	2 requests	Per hour per user
Reporting API	30 requests	Per minute per publisher

warning

Exceeding rate limits returns HTTP status 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 account representative.

---

Publisher Lookups

note

Publishers cannot be created via the API and must be provisioned via a Teads Account Manager.

Publishers Collection

Retrieve all Publishers associated with the current user:

GET https://api.outbrain.com/engage/v2/publishers
Header: OB-TOKEN-V1: <your_token>

Widgets Collection

Retrieve all Widgets associated with publisher external ID {id}:

GET https://api.outbrain.com/engage/v2/publishers/{id}/widgets
Header: OB-TOKEN-V1: <your_token>

Nativeapps Collection

Retrieve all native apps associated with publisher external ID {id}:

GET https://api.outbrain.com/engage/v2/publishers/{id}/nativeapps
Header: OB-TOKEN-V1: <your_token>

---

General Lookups

Countries Collection

Retrieve a list of all countries:

GET https://api.outbrain.com/engage/v2/countries
Header: OB-TOKEN-V1: <your_token>

Timezones Collection

Retrieve a list of all timezones:

GET https://api.outbrain.com/engage/v2/timezones
Header: OB-TOKEN-V1: <your_token>

---

Reports

Overview

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	Array of OutbrainReportItems matching criteria.
totalItems	Number	Count of the total results after filtering.
metricsSums	Object	Aggregated metrics for the returned set of data.

Filter Parameters

Operator	Type	Description	Example
:eq:	Numeric	Equal	outbrain?filter=revenue:eq:2000
:gt:	Numeric	Greater than	outbrain?filter=organicClicks:gt:300
:lt:	Numeric	Less than	outbrain?filter=paidClicks:lt:890
:between:	Numeric	Between	outbrain?filter=revenue:between:20,900
:in:	List	In	outbrain?filter=widget:in:2089,84984,38984
:not_in:	List	Not in	outbrain?filter=widget:not_in:2089,8466
:contains:	String	Contains	outbrain?filter=referrer:contains:ar
:not_contains:	String	Not contains	outbrain?filter=referrer:not_contains:ar

Chaining Filters

Chain filters with semicolons (;):

filter=revenue:gt:2000;widget:in:234,657

Note: Nesting of Boolean operators is not currently supported.

OutbrainReportItems Fields

Property	Type	Description	Breakdown Availability
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 pageviews with at least one paid link	Not available on widget breakdown
totalPvs	Number	Total pageviews with at least one link	Not available on widget breakdown
paidReqs	Number	Total paid widget requests	Available only on widget breakdown
totalReqs	Number	Total widget requests	Available only on widget breakdown
revenue	Number	Total revenue	All
rpmByPvs	Number	(Revenue / paidPvs) * 1000	All
reqsRpm	Number	(Revenue / paidReqs) * 1000	All
paidClicks	Number	Total paid clicks	All
organicClicks	Number	Total organic clicks	All
totalClicks	Number	Total clicks	All
paidCtrByPvs	Number	Average CTR: (Paid clicks / paidPvs) * 100	All
totalCtrByPvs	Number	Average CTR: (Total clicks / totalPvs) * 100	All
reqsPaidCtr	Number	Average CTR: (Paid clicks / paidReqs) * 100	All
reqsTotalCtr	Number	Average CTR: (Total clicks / totalReqs) * 100	All
organicPvs	Number	Total pageviews with at least one organic link	Not available on widget breakdown
organicReqs	Number	Total organic widget requests	Available only on widget breakdown
organicCtrByPvs	Number	Average CTR: (Organic clicks / organicPvs) * 100	All
reqsOrganicCtr	Number	Average CTR: (Organic clicks / organicReqs) * 100	All
videoRevenue	Number	Net revenue generated from video	All
videoPlays	Number	Number of video plays	All
viewabilityRate	Number	Viewability percentage: (Widget exposed / Widget served) * 100	All
paidViewabilityRate	Number	(Paid widget exposed / Paid widget served) * 100	All
organicViewabilityRate	Number	(Organic widget exposed / Organic widget served) * 100	All
viewableCtr	Number	(Total clicks / [totalReqs * viewabilityRate]) * 100	All
viewableOrganicCtr	Number	(Organic clicks / [organicReqs * organicViewabilityRate]) * 100	All
viewablePaidCtr	Number	(Paid clicks / [paidReqs * paidViewabilityRate]) * 100	All
viewableRpm	Number	Revenue per 1,000 paid in-view requests	All
optInRateByReqs	Number	Consent rate by requests: (Opt-in reqs / Total reqs) * 100	Not on doc breakdown
optInRateByPvs	Number	Consent rate by page views: (Opt-in PVs / Total PVs) * 100	Not on doc 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.
fromDate	String	Yes	Start date-time (yyyyMMdd).
toDate	String	Yes	End date-time (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.
decDigits	Number	No	Decimal places for revenue (0–6). Default: 2.

Breakdowns

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}

Chaining Breakdowns

Chain breakdowns with commas: breakdowns=day,widget (up to 4 breakdowns).

Unsupported Breakdown Combinations

The following breakdown pairs are not supported together:

• day + month
• referrer + country
• referrer + doc
• country + doc

Note: Document (doc) level breakdown is only available for data within the last 12 months.

---

Error Handling

When the API returns an error status code, JSON details are returned:

{
  "moreInfo": "getWidgets",
  "errorMessage": "access denied"
}

---

Troubleshooting

1. Community Support: Join and post in the Engage API Google Group.
2. Trace Header: Include the x-traceid header from the response when contacting support.