Reporting API
Overview
The Rokt Reporting API enables advertisers and partners to retrieve their performance data from the Rokt platform to build their own reports and dashboards. It's an HTTP-based API that can be used to programmatically query and integrate Rokt data into external business applications. The API works with any language that supports making HTTP requests. Almost all requests are passed to the https://api.rokt.com host URL.
To keep your data safe and secure, the Rokt Reporting API uses access tokens to authenticate requests. Access tokens allow Rokt to identify client applications and the type of data being accessed, as well as prevent malicious apps from accessing data that they should not be able to see.
Authentication to the API is performed via OAuth 2.0. To make a successful API call, you need to use an App ID and App Secret to obtain an access token. API requests without authentication will fail. The Rokt Reporting API only allows you to retrieve data from the accounts that your user credentials have access to.
Version
For early adopters using the Alpha Release version of the API, make sure "rokt-version":"alpha-20200701" is used in your API request header to minimize possible breaking change. If no rokt-version header is used, your endpoint request will always point to the LATEST version of the Rokt Reporting API.
Authentication
The Rokt Reporting API leverages the OAuth 2.0 approach to client integration. See the OAuth 2.0 Credentials Flow for more details. You need to use your Rokt App ID and App Secret to access the Rokt Reporting API.
The steps to generate the App ID and App Secret are explained below. You can generate credentials for the Rokt Event API with these same steps.
You need to use these client app credentials in the REST interactions with the Rokt Reporting API.
Generating App ID and App Secret
Sign in to One Platform at my.rokt.com.
Navigate to Profile Settings under your account icon at the bottom left.
Scroll down to the Generate Personal API Credentials section.
Enter the name of your app.
Click Generate.
Your credentials for both the Reporting API and Event API will generate right away and will look something like this:
AppId: "40svbin0d194subpohl079rhck"
AppSecret: "1dimhvr1v6skae9uhvtgs3chs2astnjf0469df6ul9hurubtoovn"Store the App ID and App Secret in a secure location. You will not have access to the App Secret again after this session.
You can use these credentials right away.
You should keep the credentials confidential in order to protect your account and they should never be emailed. Do not share them outside your organization, even if an inquiry appears to come from Rokt. No one who legitimately represents Rokt will ever ask you for your App Secret.
Getting an access token
An access token is needed to call any endpoint on the Rokt Reporting API. Access tokens allow Rokt to identify client apps, the type of data that each client app is accessing, and prevent malicious apps from accessing data that they do not have access to.
Authentication to the API is performed via OAuth 2.0. To run a successful API call, you will need to use an App ID and App Secret to obtain an access token that will need to be used in all API calls. App ID and App Secret can be generated on the Profile Settings page in One Platform as described above.
API requests without authentication or with incorrect authentication will fail. The API will return either a 400 or 403 error code. From the Rokt Reporting API, you can only retrieve data from the accounts that your user credentials have access to.
Access tokens are generated based on the App ID and App Secret created in the previous step. The access token lasts one hour. During that hour the access token can be used to call all endpoints on the Rokt Reporting API. Before it expires, you need to re-generate the access token based on the client app credentials.
In order to get the access token, an endpoint is exposed in the Rokt Reporting API:
POST https://api.rokt.com/auth/oauth2/token
Request parameters in header
| Key | In | Description | Required? | Example |
|---|---|---|---|---|
Authorization | header | app_id and app_secret must be passed in the authorization header through Basic HTTP authorization and can be generated under Profile Settings in One Platform; the header content is Basic base64encode(app_id:app_secret) | Yes | Basic base64encocde(12345:abcde) |
Content-Type | header | Media type of request must always be application/x-www-form-urlencoded | Yes | application/x-www-form-urlencoded |
Request parameters in body
| Key | In | Description | Required? | Example |
|---|---|---|---|---|
grant_type | body | Must be client_credentials | Yes | client_credentials |
Example successful request
Sample request:
curl -vX POST https://api.rokt.com/auth/oauth2/token \
-H 'Authorization: Basic ${AuthToken}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials'
Sample response:
{
"access_token": "eyJraWQiOiJPVUpHT1RjM09FWXROakkzUlMwME5UUkJMVGxCTkRrdFJqWXdOVVV3UkRNNE1FTTJDZz09IiwiYWxnIjoiSFMyNTYifQ.eyJzdWIiOiJkZW1vIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJyZXBvcnQtYXBpL3JlYWQtcmVwb3J0LWFwaSIsImF1dGhfdGltZSI6MTU4NTExMDA0MSwiaXNzIjoiaHR0cHM6Ly9jb2duaXRvLWlkcC51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS91cy13ZXN0LTJfZG93Tlp1elRYIiwiZXhwIjoxNTg1MTEzNjQxLCJpYXQiOjE1ODUxMTAwNDEsInZlcnNpb24iOjIsImp0aSI6IkYwNzY5RDVDLTRDNTAtNDVDOC04OTcyLTI4MkUwODlDMkFFOSIsImNsaWVudF9pZCI6ImRlbW8ifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA",
"expires_in": 3600,
"token_type": "Bearer"
}
API Endpoints
Calling an API endpoint
Using the access token from the previous step, you can now call endpoints on the Rokt Reporting API. Note that the token must be sent as a Bearer token in the Authorization header.
Sample API request:
GET https://api.rokt.com/reporting/performance-reports/partner/1/stats?dateStart=2020-02-05&dateEnd=2020-02-12&
Authorization=Bearer "eyJraWQiOiJNMDJyQmZzT3pNKzRVMjhHRjVuaDdIREphWlIwaytDMlwvNFl5dXYxZ2N0ST0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0MHN2YmluMGQxOTRzdWJwb2hsMDc5cmhjayIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoicmVwb3J0LWFwaVwvcmVhZC1yZXBvcnQtYXBpIiwiYXV0aF90aW1lIjoxNTg1MTEwMDQxLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtd2VzdC0yLmFtYXpvbmF3cy5jb21cL3VzLXdlc3QtMl9kb3dOWnV6VFgiLCJleHAiOjE1ODUxMTM2NDEsImlhdCI6MTU4NTExMDA0MSwidmVyc2lvbiI6MiwianRpIjoiZDFlNjgyMDYtNWVlNy00NThjLTkwODYtZjAwYjhiMjEzYjJhIiwiY2xpZW50X2lkIjoiNDBzdmJpbjBkMTk0c3VicG9obDA3OXJoY2sifQ.NOJIx7qLHFVXqKNZfJKsJlwitOvbHOLdknQ\_D33WjYe8O9ZE08t7LFgs7ANiwBicN5ejmdS7iND0cth5ViUWK5MKZxvLKI6dPG5RljegfpZJtGKqDT\_MFfpayvcOlkkZc5yRw9Bcgz\_fW2ha7q6BGRsUb-e9DZ0Pcb5zL\_HbRLbnvlhYCYi9rPmYOYG6BronvLwB8sg2kVubLQGn\_ASbK\_FW8bKPhqH4BL2\_JunGBzUKJPL9yNvOnFy7VKwlvH1OKUqKlCYbewOtUd1utcMNIb\_AbSGRtzJKslbE5VwQtL5bZ34kOCNH07gSolSGvqqw4dyxU4l0QSVXVmqgVYdKfA"
GET Account Campaigns Breakdown
Returns performance metrics for a Rokt Ads advertiser account's total activity for a given time period, time zone, and currency. By default, the result is broken down by campaign, but you may also break out activity by country.
Description
Call this API endpoint to receive account-level data broken down by camapignid for a specified time period, time zone, and currency. The attributes that may be called through the "groupby" parameter include:
- country
Request
Path
GET /reporting/accounts/{accountId}/campaigns/breakdown
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired time zone can in Olson format | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | Your Rokt Account ID. Found in One Platform or provided by your account manager. | true |
Response
200 OK
{
"groupByValue": "string",
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"campaignCountries": 0,
"campaigns": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"creatives": 0,
"Audiences": 0,
"campaignName": "string"
}
GET Account Summary
Returns performance metrics for an account's total activity for a given time period, time zone, and currency. This API endpoint may be used for both Rokt Ecommerce partner account data and Rokt Ads advertiser account data.
Description
Call this API endpoint to receive account-level performance metrics for a specified time period, time zone, and currency.
Request
Path
GET /reporting/accounts/{accountId}/summary
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true |
Response
200 OK
{
"campaignsSummary": {
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"campaigns": 0,
"creatives": 0,
"audiences": 0,
"campaignCountries": 0
},
"transactionsSummary": {
"revenue": 0,
"transactions": 0,
"placementImpressions": 0,
"impressions": 0,
"referrals": 0,
"rpt": 0,
"rpm": 0,
"positivePlacementEngagements": 0,
"purchases": 0
}
}
GET Account Transactions Overview
Returns performance metrics for a Rokt Ecommerce partner account over a given time period, time zone, and currency.
Description
Call this API endpoint to receive account-level transaction metrics like placement impressions, referrals, and revenue for a specified time period, time zone, and currency.
Request
Path
GET /reporting/accounts/{accountId}/transactions/overview
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true |
Response
200 OK
{
"revenue": 0,
"transactions": 0,
"placementImpressions": 0,
"impressions": 0,
"referrals": 0,
"rpt": 0,
"rpm": 0,
"positivePlacementEngagements": 0,
"purchases": 0
}
GET Account Transactions Breakdown
Returns performance metrics for a Rokt Ecommerce partner account broken down by an attribute for a given time period, time zone, and currency.
Description
Call this API endpoint to receive account-level transaction metrics broken down by an attribute specified in the query string for a specified time period, time zone, and currency. The attributes that may be called through the "groupby" parameter include:
- age
- gender
- page
- pagetype
- placement
- position
The placement breakdown does not return results for page-level metrics including transactions, purchases, or RPT.
Request
Path
GET /reporting/accounts/{accountId}/transactions/breakdown
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true |
Response
200 OK
{
"groupByValue": "string",
"revenue": 0,
"transactions": 0,
"placementImpressions": 0,
"impressions": 0,
"referrals": 0,
"purchases": 0,
"positivePlacementEngagements": 0,
"rpt": 0,
"rpm": 0
}
GET Audience Metadata
Description
Call this API endpoint to receive audience metadata, like audience name, age range, gender, and device.
Request
Path
GET /metadata/accounts/{accountId}/campaigns/{campaignId}/audiences/{audienceId}
Parameters
| Name | Type | In | Required |
|---|---|---|---|
accountId | String | path | true |
campaignId | String | path | true |
audienceId | String | path | true |
Response
200 OK
{
"accountId": "string",
"campaignId": "string",
"audienceId": "string",
"name": "string",
"ageRange": {
"min": 0,
"max": 0
},
"device": {
"desktop": true,
"tablet": true,
"mobile": true
},
"gender": "string"
}
GET Campaign Overview
Returns performance metrics for a campaign for a specified time period, time zone, and currency.
Description
Call this API endpoint to receive campaign-level performance metrics, like impressions, referrals, and conversions for a specified time period, time zone, and currency.
Request
Path
GET /reporting/accounts/{accountId}/campaigns/{campaignId}/overview
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true | ||
campaignId | String | path | true |
Response
200 OK
{
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"campaigns": 0,
"creatives": 0,
"audiences": 0,
"campaignCountries": 0
}
GET Campaign Breakdown
Returns performance metrics for a campaign broken down by country, campaign, audience or creative for a specified time period, time zone, or currency.
Description
Call this API endpoint to receive campaign-level data broken down by an attribute specified in the query string for a specified time period, time zone, or currency. The attributes that may be called through the "groupby" parameter include:
- country;
- campaign;
- audience;
- creative; or
- subvertical.
Request
Path
GET /reporting/accounts/{accountId}/campaigns/{campaignId}/breakdown?groupby=creative
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true | ||
campaignId | String | path | true |
Response
200 OK
{
"groupByValue": "string",
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"campaigns": 0,
"creatives": 0,
"audiences": 0,
"campaignCountries": 0,
"creativeName": "string"
}
GET Campaign Histogram
Returns performance metrics for a campaign for a given time period, time zone, and currency broken down by time period.
Description
Call this API endpoint to receive a histogram of a campaign's performance metrics, like impressions, referrals, or conversions for a specified time period, time zone, and currency.
Request
Path
GET /reporting/accounts/{accountId}/campaigns/{campaignId}/histogram
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true | ||
campaignId | String | path | true |
Response
200 OK
{
"intervalTimestamp": "string",
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"campaigns": 0,
"creatives": 0,
"audiences": 0,
"campaignCountries": 0
},
{
"intervalTimestamp": "string",
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"campaigns": 0,
"creatives": 0,
"audiences": 0,
"campaignCountries": 0
}
GET Campaign Metadata
Description
Call this API endpoint to receive metadata for a specific campaign.
Request
Path
GET /metadata/accounts/{accountId}/campaigns/{campaignId}
Parameters
| Name | Type | In | Required |
|---|---|---|---|
accountId | String | path | true |
campaignId | String | path | true |
Response
200 OK
{
"accountId": "string",
"campaignId": "string",
"campaignName": "string",
"campaignType": "string",
"campaignObjective": "string",
"countryCode": "string",
"status": "string"
}
GET Creative Overview
Returns performance metrics for a creative for a given time period, time zone and currency.
Description
Call this API endpoint for creative-level performance metrics, like impressions, referrals, and conversions for a specified time period, time zone, and currency.
Request
Path
GET /reporting/accounts/{accountId}/campaigns/{campaignId}/creatives/{creativeId}/overview
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
| dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
| dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
| currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
| timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
| accountId | String | path | true | ||
| campaignId | String | path | true | ||
| creativeId | String | path | true |
Response
200 OK
{
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"referrals": 0,
"uniqueReferrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"creatives": 0,
"audiences": 0
}
GET Creative Breakdown
Returns performance metrics for a creative broken down by an attribute for a specified time period, time zone, and currency.
Description
Call this API endpoint for details about a specific creative broken down by an attribute specified in the query string for a specified time period, time zone, and currency. The attributes that may be called through the "groupby" parameter is:
- audience;
Request
Path
GET /reporting/accounts/{accountId}/campaigns/{campaignId}/creatives/{creativeId}/breakdown
Parameters
| Name | Type | In | Description | Required | Example |
|---|---|---|---|---|---|
dateStart | String | query | Start time of the requested date/time range | true | dateStart=2020-03-01T00:00:00.000 |
dateEnd | String | query | End time of the requested date/time range | true | dateEnd=2020-03-31T23:59:59.000 |
currency | Enum: AUD CAD EUR GBP JPY NZD SGD USD KRW CNY | query | Currency code in which you will receive monetary metrics. | true | currency=USD |
timeZoneVariation | Enum: America/Chicago Pacific/Honolulu Australia/Sydney | query | Desired timezone can be passed through this parameter. It has to be in Olson format. | true | timeZoneVariation=Australia/Sydney |
accountId | String | path | true | ||
campaignId | String | path | true | ||
creativeId | String | path | true |
Response
200 OK
{
"groupByValue": "string",
"grossCost": 0,
"netCost": 0,
"impressions": 0,
"uniqueReferrals": 0,
"referrals": 0,
"acquisitionsByConversionDate": 0,
"acquisitionsByReferralDate": 0,
"creatives": 0,
"audiences": 0
}
GET Creative Metadata
Description
Call this API endpoint to receive creative metadata, including creative name, title, subtitle, text, responses, and status.
Request
Path
GET /metadata/accounts/{accountId}/campaigns/{campaignId}/creatives/{creativeId}
Parameters
| Name | Type | In | Required |
|---|---|---|---|
accountId | String | path | true |
campaignId | String | path | true |
creativeId | String | path | true |
Response
200 OK
{
"accountId": "string",
"campaignId": "string",
"creativeId": "string",
"name": "string",
"title": "string",
"subtitle": "string",
"text": "string",
"responses": [
"string"
],
"status": "string"
}