Engage External ID API V2

Overview

This API describes the interfaces for interacting with the Teads Engage Reports product. More information about Engage can be found on the Outbrain Engage website.

The API is RESTful and structured around core entities:

• Publisher: A publisher account
• Report: A variety of analytics entities to retrieve metrics

The following operations may be performed via this API:

Entity	Supported Operations
Publishers	Read (GET)
Widgets	Read (GET)
Report - External Id	Read (GET)

Report Granularity

"Report" refers to the External Id Report V2 aggregated per hour.

HTTP Methods

Method	Action
GET	Retrieve a resource or a 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 does not have permission.
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

V2 features 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.

Migration Example (V1 → V2)

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

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

---

Authentication

Overview

Include a 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.
• You can generate multiple active tokens concurrently without invalidating prior tokens.
• When an account password or email is changed, all prior tokens are revoked immediately.

Obtaining a Token

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

• 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 header:

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

Token Management

Because of rate limits on the /login endpoint, cache an active token and refresh it periodically (every 30 days or less).

---

Rate Limits

Scope	Limit	Window
Authentication (/login)	2 requests	Per hour per user
Publisher reporting	30 requests	Per minute per publisher
Unique variants	100,000 (100K)	Per hour

warning

Rate limit violations return HTTP status code 429 (Too Many Requests).

---

Users

Users represent individual account access to Teads services and 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.

---

Setup

External ID Injection

Populate your variants/external IDs in the platform using one of the following methods:

Method 1: Global Variables

• OB_extId — for externalId
• OB_extIdSecondary — for externalSecondaryId

Method 2: HTML Attributes

• data-external-id — for externalId
• data-external-secondary-id — for externalSecondaryId

AMP Pages Example

<amp-embed
  width="100"
  height="100"
  type="outbrain"
  data-widgetids="AMP_1"
  data-external-id="555"
  data-external-secondary-id="444">
</amp-embed>

Data Availability

External ID data becomes available for querying 48 hours after injection.

---

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 authenticated user:

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

Widgets Collection

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

GET https://api.outbrain.com/engage/v2/publishers/{id}/widgets
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	Metrics of the entities returned.
totalItems	Number	Total count of results after filtering.
metricsSums	Object	Aggregated metrics for the returned dataset after filtering.

Filter Parameters

Operator Type	Operator	Description	Example
Numeric	:eq:	Equal	externalId?filter=revenue:eq:2000
Numeric	:gt:	Greater than	externalId?filter=organicClicks:gt:300
Numeric	:lt:	Less than	externalId?filter=paidClicks:lt:890
Numeric	:between:	Between	externalId?filter=organicListings:between:20,900
List	:in:	In	externalId?filter=widget:in:2089,84984,38984
List	:not_in:	Not in	externalId?filter=widget:not_in:2089,8466
String	:contains:	Contains	externalId?filter=externalId:contains:ar
String	:not_contains:	Not contains	externalId?filter=externalId: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.

External Id Report V2 Response Structure

Property	Type	Description
items	Array	ExternalIdReportItems of the entities returned.
totalItems	Number	Count of the total results after filtering.
metricsSums	Object	Aggregated ExternalIdReportItems metrics after filtering.

ExternalIdReportItems Fields

Property	Type	Description
externalId	String	External ID value (max 110 characters).
widget	Widget	Widget entity (optional breakdown).
externalSecondaryId	String	Secondary external ID (max 110 characters).
totalReqs	Number	Total number of widget requests.
paidReqs	Number	Number of paid requests.
organicReqs	Number	Number of organic requests.
totalClicks	Number	Total number of clicks.
paidClicks	Number	Total number of paid clicks.
organicClicks	Number	Total number of organic clicks.
reqsTotalCtr	Number	Average CTR: (Total clicks / totalReqs) * 100.
reqsPaidCtr	Number	Average CTR: (Paid clicks / paidReqs) * 100.
reqsOrganicCtr	Number	Average CTR: (Organic clicks / organicReqs) * 100.
revenue	Number	Total revenue in USD.
reqsRpm	Number	Revenue per thousand requests.
videoRevenue	Number	Net revenue generated from video.
widgetViewableImpressions	Number	Total number of in-view impressions.
organicWidgetViewableImpressions	Number	Total number of organic in-view impressions.
paidWidgetViewableImpressions	Number	Total number of paid in-view impressions.

Request Structure / Parameters

Parameter	Type	Required	Details
entityId	String	Yes	External ID of the entity (publisher/group). Contact your account manager for your publisher ID.
fromDate	String	Yes	Start date-time (yyyyMMddHH or yyyyMMdd). Max range with toDate: 24 hours.
toDate	String	Yes	End date-time (yyyyMMddHH or yyyyMMdd). Max range with fromDate: 24 hours.
limit	Number	No	Max results to return. Default: 500, Max: 5000.
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 string expression.
breakdowns	Array	No	Aggregation entities. Default: externalId.
currencyCode	String	No	Revenue currency code. Default: USD.

Breakdowns

Operator	Description	Example
externalId	External ID breakdown	/v2/reports/externalId?breakdowns=externalId&entityId={entityId}
widget	Widget entity breakdown	/v2/reports/externalId?breakdowns=widget&entityId={entityId}
externalSecondaryId	Secondary external ID breakdown	/v2/reports/externalId?breakdowns=externalSecondaryId&entityId={entityId}

Chaining Breakdowns

Chain breakdowns with commas: breakdowns=externalId,widget Note: externalId is included as the primary breakdown by default.

---

Error Handling

When an error status code is returned, the response includes a descriptive JSON body:

{
  "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 response header in your inquiry to help our support team trace and resolve the issue quickly.