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 website: https://www.outbrain.com/engage

The API is RESTful and is structured into the following 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	Function
Publishers	Read
Widgets	Read
Report - External Id	Read

Note: Report refers to External Id Report V2 per hour.

HTTP Methods

HTTP Method	Action
GET	Retrieve a resource or a list of resources

HTTP Status Code Replies

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

API URL

The base URL for all API endpoints is: https://api.outbrain.com/engage/v2

What's New in V2?

V2 features enhanced security by protecting your publisher ID, making it a hashed string (both for Request and Response). Please contact your Teads account manager to acquire this ID.

Migration Example (V1 → V2)

V1: api.outbrain.com/engage/v1/reports/externalId/publishers/publisherId..
V2: api.outbrain.com/engage/v2/reports/externalId?entityId=extPublisherId..

Authentication

Overview

You must include a token in all API requests using the HTTP header OB-TOKEN-V1. Tokens are valid for 30 days. You cannot access the Engage API using an expired token. You can generate as many tokens as you wish, and generating a new token does not invalidate older tokens.

When a user password or email is changed, all tokens generated prior to the change are revoked and a new token must be generated.

Obtaining a Token

The /login endpoint is the only API transaction in which you need to supply your Teads credentials using Basic Authentication.

The HTTP Request should include the following header:

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

All communication to the Engage API is HTTPS, so your credentials are safe.

cURL Example

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

To see the Authorization HTTP header, add the -v flag:

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

Token Management

Given the limitation on /login requests (see Rate Limits section), the recommended way to manage tokens is to:

1. Store an active token to be used in all requests
2. Periodically update it
3. Since each token is valid for 30 days, the update period should be 30 days or less

Rate Limits

The following rate limits are enforced at different levels of the API:

• Authentication requests (/login): Limited to 2 requests per hour per user
• Publisher reporting: Each publisher is limited to 30 requests per minute for the entire reporting API
• Unique variants: The API supports up to 100,000 (100K) unique variants per hour

In any case of rate limit violation, the response status will be 429 (Too Many Requests).

Users

Users represent a single person's access to Teads services and 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.

Setup

External ID Injection

As a first step, populate your variants/external IDs in the platform. You can inject your variant using one of the following two 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

External ID setup is currently supported on web pages and AMP pages. Here's an example for AMP pages:

<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

After 48 hours, you can start pulling this data using the API.

Publisher Lookups

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

Publishers Collection

Retrieve all Publishers associated with the current user (as identified by the token in the OB-TOKEN-V1 HTTP header).

Widgets Collection

Retrieve all Widgets associated with the publisher with EXTERNAL ID {id} (as identified by the token in the OB-TOKEN-V1 HTTP header).

Reports

Overview

Report endpoints allow you to retrieve metrics at various levels of granularity.

Note: Performance reports have a 2-4 hours delay; therefore, 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	—
totalItems	Number	Count of the total results after filtering	—
metricsSums	Metrics	Aggregated metrics for the set of data returned in this response after filtering	See report-specific metrics

Filter Parameters

The following table describes the basic filter operators:

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

You can chain filters with ;, for example: filter=revenue:gt:2000;widget:in:234,657

Note: Nesting of Boolean operators is not supported currently.

External Id Report V2 Response Structure

Property	Type	Semantic	Comments
items	Array	ExternalIdReportItems of the entities returned	—
totalItems	Number	Count of the total results after filtering	—
metricsSums	ExternalIdReportItems	Aggregated metrics for the set of data returned in this response after filtering	—

ExternalIdReportItems Fields

Property	Type	Semantic	Comments
externalId	String	External ID value	Maximum length: 110 characters
widget	Widget	Widget entity	Optional breakdown
externalSecondaryId	String	Secondary external ID	Maximum length: 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 (Click Through Rate): (Total clicks / totalReqs) * 100	—
reqsPaidCtr	Number	Average CTR (Click Through Rate): (Paid clicks / paidReqs) * 100	—
reqsOrganicCtr	Number	Average CTR (Click Through Rate): (Organic clicks / organicReqs) * 100	—
revenue	Number	Total revenue	—
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	Semantic	Details
entityId	String	External ID of the entity (publisher/group)	Required. Contact your Teads account manager for your publisher external ID
fromDate	String	Start date-time of results	Required. Format: yyyyMMddHH or yyyyMMdd (alias for 00 hour). Maximum range with toDate: 24 hours
toDate	String	End date-time of results	Required. Format: yyyyMMddHH or yyyyMMdd (alias for 00 hour of next date). Maximum range with fromDate: 24 hours
limit	Number	Maximal number of results to return	Optional. Default: 500, Maximum: 5000
offset	Number	Ordinal number of the first result to retrieve	Optional. Default: 0
sort	String	Sorting field (metric or entity) of results	Optional. Default: revenue
order	String	Sorting order of results	Optional. Allowed values: asc or desc. Default: descending
filter	String	Filter based on filtering guidelines	Optional
breakdowns	Array of Strings	Aggregation entities of results	Optional. Default: externalId
currencyCode	String	Revenue currency code	Optional. Default: USD

Breakdowns

The following table describes the aggregation options (report 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}

You can chain breakdowns with ,, for example: breakdowns=externalId,widget

Note: ExternalId is included as the first breakdown by default. To make it a different position, indicate it explicitly: breakdowns=widget,externalId

Error Handling

When the API returns a status code indicating an error (400, 401, 403, 404, 429), it will also include JSON describing the error.

Error Response Example

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

Troubleshooting

If you're experiencing any issues or difficulties, please post a new topic in the Google group:

https://groups.google.com/forum/#!forum/engageapi

When reporting issues, please attach the x-traceid header from the returned response. This header allows the support team to identify your unique request and helps them to reply quicker and more efficiently.

For questions, feature requests, or announcements about new features, please join the Google group:

https://groups.google.com/forum/#!forum/engageapi