Overview

Taboola Newsroom provides a turnkey solution for viewing article performance (based on page views or subscriptions), filtering data by subscribers or guests, and more.

Nonetheless, publishers that prefer to build their own dashboards or run their own reports can use the Taboola Newsroom API.

Authentication

Overview

Taboola Newsroom API uses OAuth2 for authentication. An Access Token must be retrieved and attached to the Authorization header of each request, in this format:

Authorization: Bearer <token>

Fetch an access token

An Access Token can be retrieved via the following endpoint, using a valid client_id and client_secret:

curl 'https://authentication.taboola.com/authentication/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=[client_id]' \
--data-urlencode 'client_secret=[client_secret]' \
--data-urlencode 'grant_type=client_credentials'

POST /authentication/oauth/token
Content-Type: application/x-www-form-urlencoded
Host: authentication.taboola.com

client_id=[client_id]&client_secret=[client_secret]&grant_type=client_credentials

Sample request:

curl 'https://authentication.taboola.com/authentication/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=3acdf166e55fc583345e731510c29011' \
--data-urlencode 'client_secret=22a886f1a6014a658ae953e61ec535db' \
--data-urlencode 'grant_type=client_credentials'

POST /authentication/oauth/token
Content-Type: application/x-www-form-urlencoded
Host: authentication.taboola.com

client_id=3acdf166e55fc583345e731510c29011&client_secret=22a886f1a6014a658ae953e61ec535db&grant_type=client_credentials

🚧
You above code snippet is provided as a demonstration only.
Make sure to use your your own credentials in your solution.

Sample response:

{  
    "access_token": "Ce0MAAEfAgAAAfawE2NTN2ZmZjZjYzU0MDczNTA3NUAC::46cf39::a981aa",  
    "token_type": "bearer",  
    "expires_in": 43199  
}

For each subsequent request, attach the retrieved token to the Authorization header - e.g.:

Authorization: Bearer Ce0MAAEfAgAAAfawE2NTN2ZmZjZjYzU0MDczNTA3NUAC::46cf39::a981aa

🚧
A token expires after 12 hours.

Get a list of articles

curl 'https://api-newsroom.taboola.com/api/v3/publisher/[pubID]/articlelist?[query params]' \
--header 'Authorization: Bearer [Access Token]'

GET /api/v3/publisher/[pubID]/articlelist?[query params]
Host: api-newsroom.taboola.com
Authorization: Bearer [Access Token]

📘
PubID path param
(Required) Your numeric Taboola Newsroom Publisher ID, as provided by Taboola.

📘
Query params
To specify which data to return, pass the relevant query params (see sections below).
Note that certain query params are required.

Query params

To specify which data to return, pass the relevant query params:

Param	Description
`timerange`*	(Required) Data time range. See 'Commonly used values' (below).
`aggregationtype`*	(Required) Traffic aggregation type. See 'Commonly used values' (below).
`sortdimension`	Top articles sorting criteria. See 'Commonly used values' (below).
`reportdimension`	Filter by user type. Equivalent to sorting by Subscribers/Registered Users, if enabled in Newsroom.
`filter`	Filter by a URL-encoded article title.
`page`	Specifies which page of results to return - `1`, `2`, `3`, etc.

Commonly used values

The following table illustrates some commonly used values:

Param	Commonly used values
`timerange`	`1d`, `7d`, `30d`, `yesterday`
`aggregationtype`	`all`, `social, search`, `direct`, `other`
`sortdimension`	`pageview`, `score`, `bouncerate`, `timeonpage`, `socialengagementrate`, `videowatchrate`
`reportdimension`	`subscription`, `registereduser`

Sample request

Request the top 20 articles over the last day, across all traffic types:

curl 'https://api-newsroom.taboola.com/api/v3/publisher/{user.pubID}/articlelist?timerange=1d&aggregationtype=all&page=1' \
--header 'Authorization: Bearer CRIRAAAAAAAAEax6AgAAAAAAGAEgACnP3EEGkwEAADooYzkyOTRiMjk5NzZkOWEzNzUzMzA5MjRjMjI2Y2RiNTRmZTliODE1OEAC::1127e5::14d6b5'

GET /api/v3/publisher/{user.pubID}/articlelist?timerange=1d&aggregationtype=all&page=1
Host: api-newsroom.taboola.com
Authorization: Bearer CRIRAAAAAAAAEax6AgAAAAAAGAEgACnP3EEGkwEAADooYzkyOTRiMjk5NzZkOWEzNzUzMzA5MjRjMjI2Y2RiNTRmZTliODE1OEAC::1127e5::14d6b5'

📘
Query params
The following query params were used in the above example:

page=1 => fetch the top 20 results

timerange=1d=> over the past day

aggregationtype=all => across all traffic types

Response schema

Top-level fields

{  
    "schema": [  
        "pageView",  
        "pageViewScore",  
        "combinedZScore",  
        "combinedScore",  
        "bounceRate",  
        ...  
    ],  
    "timeStamps": {...},  
    "metadata": {...},  
    "articles": [...]
}

📘
Top-level fields

schema - A list of column names that map to the data points in the "overall" field, for each article object.

metadata - A simple object with 2 fields:

"sortDimension" - e.g. "pageview"

count - the ranking of the last article on this page of results (e.g. 20 for page 1, 40 for page 2, 60 for page 3, etc.)

articles- A collection of article objects.

The `article` object

Field	Type	Description
`overall`	`array`	A collection of aggregate values for the time range provided. Each data point maps to the corresponding column under`"schema"` (see above) -- Example: Refer to the `"schema"` field in the sample response (above) - and the `"overall"` field in the sample object (below*): `pageView` => `15098` `pageViewScore` => `100` `combinedZScore` => `90.5` `...`
`title`	`string`	Article title
`url`	`string`	Article URL
`imageUrl`	`string`	Article thumbnail URL
`publishTime`	`string`	Article publish time (for publisher’s time zone)
`section`	`object`	Article section name and ID
`author`	`object`	Article author name and ID
`premium`	`boolean`	Indicates if the article is premium

{  
    "id": "e41b8742199c1d81",  
    "publisherId": 1003128,  
    "metadata": {...},  
    "overall": [  
        15098, 100, 90.5, 91, 0.0676, ...  
    ],  
    "title": "Article Title",  
    "url": "Article URL",  
    "imageUrl": "Article Thumbnail URL",  
    "publishTime": "201905310800",  
    "section": {  
        "name": "travel",  
        "id": "6303dc32561ceb69"  
    },  
    "author": [  
        {  
            "name": "Author Name",  
            "id": "8cf3d79ba08fa0c2"  
        }  
    ],  
    "premium": false,  
    "metrics": {...},  
    "latestBucketPageViews": 1462,  
    "latestBucketCategoryPageViews": {  
        "other": 101,  
        "search": 431,  
        "social": 394,  
        "direct": 536  
    }  
}

Overview

Authentication

Overview

Fetch an access token

Get a list of articles

PubID path param

Query params

Query params

Commonly used values

Sample request

Query params

Response schema

Top-level fields

Top-level fields

The article object

`PubID` path param

The `article` object