Query API (1.0.0)

Introduction

The Rokt Query API is a comprehensive and flexible API for querying account data, campaigns, and transactions.

Authentication

The Rokt Query 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 Query API.

Generating a Rokt 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 and click Generate
Store the App ID and App Secret securely - you will not have access to the App Secret again

Generating an Access Token

Rokt uses OAuth 2.0 for secure authentication to our public APIs. This is to ensure that only authorized users can access their data.

To generate an access token, make the following POST request.

curl -X POST https://api.rokt.com/auth/oauth2/token \
--header "Authorization: Basic $ENCODED_TOKEN" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials"

The access token expires after one hour, and must be included as a Bearer token in all API requests.

Step-by-Step Example

Here's a complete example using shell commands:

# Step 1: Set your environment variables. Do not store these in version control
export ROKT_APP_ID="your_app_id"
export ROKT_APP_SECRET="your_secret"

# Step 2: Encode your credentials to generate an auth token
export ENCODED_TOKEN=$(printf '%s' "${ROKT_APP_ID}:${ROKT_APP_SECRET}" | openssl base64 | tr -d '\n')

# Step 3: Request OAuth2/Bearer token using Basic Auth with the encoded token
BEARER_TOKEN=$(curl -s -X POST https://api.rokt.com/auth/oauth2/token       -H "Authorization: Basic $ENCODED_TOKEN"       -H "Content-Type: application/x-www-form-urlencoded"       -d "grant_type=client_credentials" | jq -r '.access_token')

# Step 4: Use the Bearer token in Query API requests
curl -X GET "https://api.rokt.com/v1/query/accounts" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $BEARER_TOKEN"

Important Notes

Always use environment variables for credentials to avoid exposing them in scripts or version control
The printf command with openssl base64 ensures proper encoding without newline characters
Store the access token securely as it provides full API access until expiration

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

Error Handling

The API returns standardized error responses with appropriate HTTP status codes.

accounts

Account endpoints

Get User Accounts

Retrieve all accounts associated with the authenticated user.

This endpoint returns a list of all accounts that the authenticated user has access to. The response includes account details such as account ID, name, country, currency, and timezone information.

Authentication

Requires a valid Bearer token from a user's Rokt JWT or encoded OAuth2 token. For more information about authenticating with our API, see the Authentication documentation.

Response

Returns a list of account objects with the following structure:

accountId: Unique identifier for the account
accountName: Display name of the account
countryCode: ISO country code for the account
accountOwner: Email address of the account owner (optional)
accountCurrencyCode: Currency code for the account
accountTimezone: Timezone name for the account
accountTimezoneOffset: Timezone offset in minutes

Error Responses

401 Unauthorized: Failed to authenticate. Invalid token.
404 Not Found: User does not have any accounts
500 Internal Server Error: Server error while retrieving accounts

Example Response

[
    {
        "accountId": "acc_123456789",
        "accountName": "Example Account 1",
        "countryCode": "US",
        "accountOwner": "user@example.com",
        "accountCurrencyCode": "USD",
        "accountTimezone": "America/New_York",
        "accountTimezoneOffset": -300
    },
    {
        "accountId": "acc_123456790",
        "accountName": "Example Account 2",
        "countryCode": "AU",
        "accountOwner": "user@example.com",
        "accountCurrencyCode": "AUD",
        "accountTimezone": "Australia/Sydney",
        "accountTimezoneOffset": 600
    }
]

Responses

Response samples

200
401
404
500

Content type

application/json

[{"accountId": "string",
"accountName": "string",
"countryCode": "string",
"accountOwner": "string",
"accountCurrencyCode": "string",
"accountTimezone": "string",
"accountTimezoneOffset": 0
}
]

Get Account

Retrieve detailed information for a specific account.

This endpoint returns detailed information about a specific account identified by the account_id parameter. The user must have access permissions to the specified account.

Parameters

accountId (path): The unique identifier of the account to retrieve

Authentication

Requires a valid Bearer token from a user's Rokt JWT or encoded OAuth2 token. For more information about authenticating with our API, see the Authentication documentation. The user must have access permissions to the specified account and campaign data.

Response

Returns a single account object with the following structure:

accountId: Unique identifier for the account
accountName: Display name of the account
countryCode: ISO country code for the account
accountOwner: Email address of the account owner (optional)
accountCurrencyCode: Currency code for the account
accountTimezone: Timezone name for the account
accountTimezoneOffset: Timezone offset in minutes

Error Responses

401 Unauthorized: Failed to authenticate. Invalid token.
403 Forbidden: User does not have access to the specified account
404 Not Found: Account with the specified ID does not exist
500 Internal Server Error: Server error while retrieving account

Example Request

GET /v1/query/accounts/acc_123456789

Example Response

{
    "accountId": "acc_123456789",
    "accountName": "Example Account 1",
    "countryCode": "US",
    "accountOwner": "user@example.com",
    "accountCurrencyCode": "USD",
    "accountTimezone": "America/New_York",
    "accountTimezoneOffset": -300
}

path Parameters

account_id

required

integer (Account Id)

Responses

Response samples

Content type

application/json

{"accountId": "string",
"accountName": "string",
"countryCode": "string",
"accountOwner": "string",
"accountCurrencyCode": "string",
"accountTimezone": "string",
"accountTimezoneOffset": 0
}

campaigns

Campaign endpoints

Get Advertiser Report

Generate a comprehensive campaign report for the specified account.

This endpoint allows you to query campaign performance data with flexible filtering, metrics selection, and date range specification. The response includes aggregated campaign data based on your specified criteria.

Parameters

account_id (path): The unique identifier of the account for which to generate the report

Request Body

The request body should contain a ReportingRequestExternal object with the following fields:

timezoneVariation (string, optional): Timezone for the report data (default: "America/New_York")
currencyCode (string, optional): Currency code for the report data (default: "USD")
interval (string, optional): Time interval for the report data. Options: "day", "week", "month", "year"
startDate (string): Start date for the report period in ISO format (inclusive). Accepts both YYYY-MM-DD and YYYY-MM-DD HH:MM:SS
endDate (string): End date for the report period in ISO format (exclusive). Accepts both YYYY-MM-DD and YYYY-MM-DD HH:MM:SS
dimensionFilters (object, optional): Filters to apply to specific dimensions
metrics (array): List of metrics to include in the report. For available metrics, use the slugs returned from the get_help endpoint.
dimensions (array, optional): Dimensions to group the data by. For available dimensions, use the slugs returned from the get_help endpoint.
orderBys (array, optional): Sorting criteria for the results. Accepts both "column" and "direction" keys.
limit (integer, optional): Maximum number of results to return

Authentication

Requires either a valid JWT Bearer token or Cognito token in the request headers. For more information about authenticating with our API, see the Authentication documentation. The user must have access permissions to the specified account and campaign data.

Response

Returns a ReportingResponseExternal object containing:

data: Array of requested campaign metrics and dimensions. If interval is provided, each object will contain a datetime field denoting the start of the provided interval.
accountId: The account ID for which the report was generated
queryTimeMs: Query execution time in milliseconds

Error Responses

400 Bad Request: Invalid request parameters or filters
401 Unauthorized: Failed to authenticate. Invalid token.
403 Forbidden: User does not have access to the specified account
404 Not Found: The requested resource was not found. Please validate your request is correct and try again.
500 Internal Server Error: Server error while generating report

Example Request

{
    "timezoneVariation": "America/New_York",
    "currencyCode": "USD",
    "interval": "day",
    "startDate": "2025-03-04",
    "endDate": "2025-03-05",
    "dimensionFilters": {
        "campaign_id": ["3427232771076128951"]
    },
    "metrics": ["impressions", "referrals", "gross_cost"],
    "dimensions": ["campaign_id", "creative_id", "age_group"],
    "orderBys": [
        {
            "column": "referrals",
            "direction": "desc"
        }
    ]
}

Example Response

{
    "data": [
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1501.0,
            "referrals": 205.0,
            "gross_cost": 410.05,
            "campaign_id": "3427232771076128951",
            "creative_id": "3427232968644886703",
            "age_group": "26-35"
        },
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1220.0,
            "referrals": 180.0,
            "gross_cost": 300.00,
            "campaign_id": "3401676908203081730",
            "creative_id": "3404563830614458492",
            "age_group": "36-45"
        }
    ],
    "accountId": "3286272607917027328",
    "queryTimeMs": 206
    }

path Parameters

account_id

required

integer (Account Id)

Request Body schema: application/json
required

timezoneVariation	string (Timezonevariation) Default: "America/New_York"
currencyCode	string (Currencycode) Default: "USD"
startDate	string (Startdate) Default: "2025-07-01T13:31:16.821359"
endDate	string (Enddate) Default: "2025-07-08T13:31:16.821386"
	Dimensionfilters (object) or Dimensionfilters (null) (Dimensionfilters) Default: {}
	Limit (integer) or Limit (null) (Limit)
metrics required	Array of strings (Metrics)
	Array of Dimensions (strings) or Dimensions (null) (Dimensions) Default: []
	Array of Orderbys (objects) or Orderbys (null) (Orderbys) Default: []
	Interval (string) or Interval (null) (Interval)

Responses

Request samples

Payload

Content type

application/json

{"timezoneVariation": "America/New_York",
"currencyCode": "USD",
"startDate": "2025-07-01T13:31:16.821359",
"endDate": "2025-07-08T13:31:16.821386",
"dimensionFilters": { },
"limit": 0,
"metrics": ["string"
],
"dimensions": [ ],
"orderBys": [ ],
"interval": "string"
}

Response samples

Content type

application/json

{"data": [{ }
],
"accountId": "string",
"queryTimeMs": 0
}

Get Help

Retrieve available metrics and dimensions for campaign reporting.

This endpoint returns metadata about the available reporting options, including which metrics and dimensions can be used together, their display names, and any additional configuration options.

Parameters

account_id (path): The unique identifier of the account (used for access validation)

Authentication

Requires a valid Bearer token from a user's Rokt JWT or encoded OAuth2 token. For more information about authenticating with our API, see the Authentication documentation. The user must have access permissions to the specified account and campaign data.

Response

Returns a ReportingMetadataExternal object containing:

dimensions: List of dimensions with their slugs and descriptions
metrics: List of metrics with their slugs and descriptions

Error Responses

401 Unauthorized: Failed to authenticate. Invalid token.
403 Forbidden: User does not have access to the specified account
404 Not Found: The requested resource was not found. Please validate your request is correct and try again.
500 Internal Server Error: Server error while retrieving metadata

Example Response

{
  "dimensions": [
      {
          "slug": "age_range",
          "description": "The age range of the user"
      },
      {
          "slug": "campaign_id",
          "description": "The ID of the campaign"
      },
      {
          "slug": "creative_id",
          "description": "The ID of the creative"
      },
      {
          "slug": "device",
          "description": "The device of the user"
      },
  ],
  "metrics": [
      {
          "slug": "impressions",
          "description": "The number of ad impressions"
      },
      {
          "slug": "referrals",
          "description": "The number of positive engagements with the ad"
      },
      {
          "slug": "clickthru_acquisitions",
          "description": "The number of click-thru acquisitions for the ad.
          An acquisition represents the first conversion
          following an engagement event."
      },
      {
          "slug": "cpa",
          "description": "The Cost per Acquisition for the ad"
      },
      {
          "slug": "gross_cost",
          "description": "The gross cost (spend) for the ad"
      },
  ]
}

path Parameters

account_id

required

integer (Account Id)

Responses

Response samples

200
401
404
422
500

Content type

application/json

{"dimensions": [{"property1": "string",
"property2": "string"
}
],
"metrics": [{"property1": "string",
"property2": "string"
}
]
}

transactions

Transaction endpoints

Get Partner Report

Generate a comprehensive transaction report for the specified account.

This endpoint allows you to query transaction data with flexible filtering, metrics selection, and date range specification. The response includes aggregated transaction data based on your specified criteria.

Parameters

account_id (path): The unique identifier of the account for which to generate the report

Request Body

The request body should contain a ReportingRequestExternal object with the following fields:

timezoneVariation (string, optional): Timezone for the report data (default: "America/New_York")
currencyCode (string, optional): Currency code for the report data (default: "USD")
interval (string, optional): Time interval for the report data. Options: "day", "week", "month", "year"
startDate (string): Start date for the report period in ISO format (inclusive). Accepts both YYYY-MM-DD and YYYY-MM-DD HH:MM:SS
endDate (string): End date for the report period in ISO format (exclusive). Accepts both YYYY-MM-DD and YYYY-MM-DD HH:MM:SS
dimensionFilters (object, optional): Filters to apply to specific dimensions
metrics (array): List of metrics to include in the report. For available metrics, use the slugs returned from the get_help endpoint.
dimensions (array, optional): Dimensions to group the data by. For available dimensions, use the slugs returned from the get_help endpoint.
orderBys (array, optional): Sorting criteria for the results. Accepts both "column" and "direction" keys.
limit (integer, optional): Maximum number of results to return

Authentication

Requires either a valid JWT Bearer token or Cognito token in the request headers. For more information about authenticating with our API, see the Authentication documentation. The user must have access permissions to the specified account and transaction data.

Response

Returns a ReportingResponseExternal object containing:

data: Array of requested transaction metrics and dimensions. If interval is provided, each object will contain a datetime field denoting the start of the provided interval.
accountId: The account ID for which the report was generated
queryTimeMs: Query execution time in milliseconds

Error Responses

400 Bad Request: Invalid request parameters or filters
401 Unauthorized: Failed to authenticate. Invalid token.
403 Forbidden: User does not have access to the specified account
404 Not Found: The requested resource was not found. Please validate your request is correct and try again.
500 Internal Server Error: Server error while generating report

Example Request

{
    "timezoneVariation": "America/New_York",
    "currencyCode": "USD",
    "interval": "day",
    "startDate": "2025-03-04",
    "endDate": "2025-03-05",
    "dimensionFilters": {
        "page_type": ["confirmation"]
    },
    "metrics": ["impressions", "referrals", "total_page_transactions"],
    "dimensions": ["display_type", "page_type", "age_range"],
    "orderBys": [
        {
            "column": "referrals",
            "direction": "desc"
        }
    ]
}

Example Response

{
    "data": [
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1501.0,
            "referrals": 205.0,
            "total_page_transactions": 1600.0,
            "display_type": "desktop",
            "page_type": "confirmation",
            "age_range": "26-35"
        },
        {
            "datetime": "2025-03-04T00:00:00Z",
            "impressions": 1220.0,
            "referrals": 180.0,
            "total_page_transactions": 1400.0,
            "display_type": "mobile",
            "page_type": "confirmation",
            "age_range": "36-45"
        }
    ],
    "accountId": "3286272607917027328",
    "queryTimeMs": 206
    }

path Parameters

account_id

required

integer (Account Id)

Request Body schema: application/json
required

timezoneVariation	string (Timezonevariation) Default: "America/New_York"
currencyCode	string (Currencycode) Default: "USD"
startDate	string (Startdate) Default: "2025-07-01T13:31:16.821359"
endDate	string (Enddate) Default: "2025-07-08T13:31:16.821386"
	Dimensionfilters (object) or Dimensionfilters (null) (Dimensionfilters) Default: {}
	Limit (integer) or Limit (null) (Limit)
metrics required	Array of strings (Metrics)
	Array of Dimensions (strings) or Dimensions (null) (Dimensions) Default: []
	Array of Orderbys (objects) or Orderbys (null) (Orderbys) Default: []
	Interval (string) or Interval (null) (Interval)

Responses

Request samples

Payload

Content type

application/json

{"timezoneVariation": "America/New_York",
"currencyCode": "USD",
"startDate": "2025-07-01T13:31:16.821359",
"endDate": "2025-07-08T13:31:16.821386",
"dimensionFilters": { },
"limit": 0,
"metrics": ["string"
],
"dimensions": [ ],
"orderBys": [ ],
"interval": "string"
}

Response samples

Content type

application/json

{"data": [{ }
],
"accountId": "string",
"queryTimeMs": 0
}

Get Help

Retrieve available metrics and dimensions for transaction reporting.

This endpoint returns metadata about the available reporting options, including which metrics and dimensions can be used together, their display names, and any additional configuration options.

Parameters

account_id (path): The unique identifier of the account (used for access validation)

Authentication

Requires a valid Bearer token from a user's Rokt JWT or encoded OAuth2 token. For more information about authenticating with our API, see the Authentication documentation. The user must have access permissions to the specified account and transaction data.

Response

Returns a ReportingMetadataExternal object containing:

dimensions: List of dimensions with their slugs and definitions
metrics: List of metrics with their slugs and definitions

Error Responses

401 Unauthorized: Failed to authenticate. Invalid token.
403 Forbidden: User does not have access to the specified account
404 Not Found: The requested resource was not found. Please validate your request is correct and try again.
500 Internal Server Error: Server error while retrieving metadata

Example Response

{
    "dimensions": [
        {
            "slug": "age_range",
            "description": "The age range of the user"
        },
        {
            "slug": "display_type",
            "description": "The type of display the ad was shown on"
        },
        {
            "slug": "page_type",
            "description": "The type of page the user was on"
        },
        {
            "slug": "device",
            "description": "The device of the user"
        },
    ],
    "metrics": [
        {
            "slug": "transactions",
            "description": "Total number of transactions"
        },
        {
            "slug": "rokt_transactions_per_transaction",
            "description": "Total number of transactions processed by Rokt per transaction"
        },
        {
            "slug": "impressions",
            "description": "Total number of advertisement impressions"
        },
        {
            "slug": "page_transactions",
            "description": "Total number of transactions processed by page"
        },
        {
            "slug": "layout_impressions",
            "description": "Total number of advertisement impressions processed by layout"
        },
    ]
}

path Parameters

account_id

required

integer (Account Id)

Responses

Response samples

200
401
404
422
500

Content type

application/json

{"dimensions": [{"property1": "string",
"property2": "string"
}
],
"metrics": [{"property1": "string",
"property2": "string"
}
]
}

Account Model

accountId required	string (Accountid)
accountName required	string (Accountname)
countryCode required	string (Countrycode)
required	Accountowner (string) or Accountowner (null) (Accountowner)
accountCurrencyCode required	string (Accountcurrencycode)
accountTimezone required	string (Accounttimezone)
accountTimezoneOffset required	integer (Accounttimezoneoffset)

{"accountId": "string",
"accountName": "string",
"countryCode": "string",
"accountOwner": "string",
"accountCurrencyCode": "string",
"accountTimezone": "string",
"accountTimezoneOffset": 0
}

Reporting Request Model

timezoneVariation	string (Timezonevariation) Default: "America/New_York"
currencyCode	string (Currencycode) Default: "USD"
startDate	string (Startdate) Default: "2025-07-01T13:31:16.821359"
endDate	string (Enddate) Default: "2025-07-08T13:31:16.821386"
	Dimensionfilters (object) or Dimensionfilters (null) (Dimensionfilters) Default: {}
	Limit (integer) or Limit (null) (Limit)
metrics required	Array of strings (Metrics)
	Array of Dimensions (strings) or Dimensions (null) (Dimensions) Default: []
	Array of Orderbys (objects) or Orderbys (null) (Orderbys) Default: []
	Interval (string) or Interval (null) (Interval)

{"timezoneVariation": "America/New_York",
"currencyCode": "USD",
"startDate": "2025-07-01T13:31:16.821359",
"endDate": "2025-07-08T13:31:16.821386",
"dimensionFilters": { },
"limit": 0,
"metrics": ["string"
],
"dimensions": [ ],
"orderBys": [ ],
"interval": "string"
}

Reporting Response Model

data required	Array of objects (Data)
accountId required	string (Accountid)
queryTimeMs required	integer (Querytimems)

{"data": [{ }
],
"accountId": "string",
"queryTimeMs": 0
}

Reporting Metadata Model

required	Array of objects (Dimensions)
required	Array of objects (Metrics)

{"dimensions": [{"property1": "string",
"property2": "string"
}
],
"metrics": [{"property1": "string",
"property2": "string"
}
]
}

Query API (1.0.0)

Introduction

Authentication

Generating a Rokt App ID and App Secret

Generating an Access Token

Step-by-Step Example

Important Notes

Rate Limiting

Error Handling

accounts

Get User Accounts

Authentication

Response

Error Responses

Example Response

Responses

Response samples

Get Account

Parameters

Authentication

Response

Error Responses

Example Request

Example Response

path Parameters

Responses

Response samples

campaigns

Get Advertiser Report

Parameters

Request Body

Authentication

Response

Error Responses

Example Request

Example Response

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Help

Parameters

Authentication

Response

Error Responses

Example Response

path Parameters

Responses

Response samples

transactions

Get Partner Report

Parameters

Request Body

Authentication

Response

Error Responses

Example Request

Example Response

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Help

Parameters

Authentication

Response

Error Responses

Example Response

path Parameters

Responses

Response samples

Account Model

Reporting Request Model

Reporting Response Model

Reporting Metadata Model

Request Body schema: application/json
required

Request Body schema: application/json
required