Skip to main content

Query API

OverviewDirect link to Overview

The Rokt Query API is a comprehensive and flexible API for querying account data, campaigns, and transactions. Check out our interactive documentation here.

AuthenticationDirect link to 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 SecretDirect link to Generating a Rokt App ID and App Secret

  1. Sign in to One Platform at my.rokt.com
  2. Navigate to Profile Settings under your account icon at the bottom left
  3. Scroll down to the Generate Personal API Credentials section
  4. Enter the name of your app and click Generate
  5. Store the App ID and App Secret securely - you will not have access to the App Secret again

Generating an Access TokenDirect link to 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 ExampleDirect link to 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 NotesDirect link to 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 LimitingDirect link to Rate Limiting

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

Error HandlingDirect link to Error Handling

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

Account APIsDirect link to Account APIs

Get User AcconutsDirect link to Get User Acconuts

Retrieve all accounts associated with the authenticated user.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
GET /v1/query/accounts
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to 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
    }
]

Get AccountDirect link to Get Account

Retrieve detailed information for a specific account.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
GET /v1/query/accounts/{account_id}
ParametersDirect link to Parameters
  • accountId (path): The unique identifier of the account to retrieve
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to Example Response
{
    "accountId": "1234567891011",
    "accountName": "Example Account 1",
    "countryCode": "US",
    "accountOwner": "user@example.com",
    "accountCurrencyCode": "USD",
    "accountTimezone": "America/New_York",
    "accountTimezoneOffset": -300
}

Advertiser APIsDirect link to Advertiser APIs

Get Advertiser ReportDirect link to Get Advertiser Report

Generate a comprehensive campaign report for the specified account.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
POST /v1/query/accounts/{account_id}/campaigns/
ParametersDirect link to Parameters
  • account_id (path): The unique identifier of the account for which to generate the report
Request BodyDirect link to Request Body

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

ParameterTypeRequiredDescriptionDefault
timezoneVariationstringoptionalTimezone for the report data"America/New_York"
currencyCodestringoptionalCurrency code for the report data"USD"
intervalstringoptionalTime interval for the report data. Options: "day", "week", "month", "year"
startDatestringrequiredStart date for the report period in ISO format (inclusive). Accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
endDatestringrequiredEnd date for the report period in ISO format (exclusive). Accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
dimensionFiltersobjectoptionalFilters to apply to specific dimensions
metricsarrayrequiredList of metrics to include in the report. Use slugs from get_help endpoint
dimensionsarrayoptionalDimensions to group the data by. Use slugs from get_help endpoint
orderBysarrayoptionalSorting criteria for the results. Accepts both "column" and "direction" keys
limitintegeroptionalMaximum number of results to return
Example RequestDirect link to 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"
        }
    ]
}
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to 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
    }

Get HelpDirect link to Get Help

Retrieve available metrics and dimensions for campaign reporting.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
GET /v1/query/accounts/{account_id}/campaigns/help
ParametersDirect link to Parameters
  • account_id (path): The unique identifier of the account (used for access validation)
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to 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"
      },
  ]
}

Partner APIsDirect link to Partner APIs

Get Partner ReportDirect link to Get Partner Report

Generate a comprehensive transaction report for the specified account.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
POST /v1/query/accounts/{account_id}/transactions
ParametersDirect link to Parameters
  • account_id (path): The unique identifier of the account for which to generate the report
Request BodyDirect link to Request Body

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

ParameterTypeRequiredDescriptionDefault
timezoneVariationstringoptionalTimezone for the report data"America/New_York"
currencyCodestringoptionalCurrency code for the report data"USD"
intervalstringoptionalTime interval for the report data. Options: "day", "week", "month", "year"
startDatestringrequiredStart date for the report period in ISO format (inclusive). Accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
endDatestringrequiredEnd date for the report period in ISO format (exclusive). Accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
dimensionFiltersobjectoptionalFilters to apply to specific dimensions
metricsarrayrequiredList of metrics to include in the report. Use slugs from get_help endpoint
dimensionsarrayoptionalDimensions to group the data by. Use slugs from get_help endpoint
orderBysarrayoptionalSorting criteria for the results. Accepts both "column" and "direction" keys
limitintegeroptionalMaximum number of results to return
Example RequestDirect link to 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"
        }
    ]
}
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to 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
    }

Get HelpDirect link to Get Help

Retrieve available metrics and dimensions for transaction reporting.

DescriptionDirect link to Description

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.

RequestDirect link to Request

PathDirect link to Path
GET /v1/query/accounts/{account_id}/transactions/help
ParametersDirect link to Parameters
  • account_id (path): The unique identifier of the account (used for access validation)
AuthenticationDirect link to 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.

ResponseDirect link to 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 ResponsesDirect link to 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 ResponseDirect link to 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"
        },
    ]
}

Available Data PointsDirect link to Available Data Points

The following dimensions and metrics are available for use with the Query API. Use the Get Help endpoints for campaigns or transactions to retrieve the exact list available for your account. The slugs below are used in request bodies for dimensions, metrics, dimensionFilters, and orderBys.

DimensionsDirect link to Dimensions

SlugDescription
age_rangeAge range of the user
audience_nameName of the audience
advertiser_idID of the advertiser
campaign_idID of the campaign
campaign_nameName of the campaign
campaign_objectiveObjective of the campaign
campaign_countryCountry of the campaign
creative_idID of the creative
creative_nameName of the creative
deviceDevice of the user
genderGender of the user
partner_sub_verticalSub-vertical of the partner
partner_verticalVertical of the partner
rankRank of the ad placement
user_countryCountry of the user
countryCountry the user is located in
stateState the user is located in
population_densityPopulation density (metropolitan, micropolitan, rural, unknown)
dmaDMA the user is located in
dma_codeDMA code the user is located in
zctaZCTA the user is located in
zip_codeZip code the user is located in
operating_systemOperating system of the user (Android, iOS, Windows, Mac OS X, etc.)
positionPosition of the placement
contains_lookalike_audienceWhether the campaign contains a lookalike audience
customer_interactivityCustomer interactivity segment
platform_typeApplication environment through which a Rokt Layout is rendered

MetricsDirect link to Metrics

SlugDescription
impressionsTotal number of advertisement impressions
referral_rateTotal number of referrals per impression
referralsTotal number of positive engagements on advertisements
click_thru_acquisitionsClick-thru acquisitions grouped by campaign time (first conversion after engagement)
click_thru_acquisitions_by_conversion_timeClick-thru acquisitions grouped by conversion time
view_thru_acquisitions_by_conversion_timeView-thru acquisitions grouped by conversion time
acquisitions_by_conversion_timeAll acquisitions grouped by conversion time
conversion_amount_fill_rateAverage fill rate of conversion amount for conversions
click_thru_conversion_rateAverage conversion rate for click-thru conversions
view_thru_conversion_rateAverage conversion rate for view-thru conversions
conversion_rateAverage conversion rate for all conversions
click_thru_conversionsTotal number of click-thru conversions
click_thru_conversions_by_conversion_timeClick-thru conversions grouped by conversion time
view_thru_conversions_by_conversion_timeView-thru conversions grouped by conversion time
click_thru_copiAverage click-thru conversions per ad impression
click_thru_cpaAverage cost per acquisition for click-thru acquisitions
view_thru_cpaAverage cost per acquisition for view-thru acquisitions
cpaAverage cost per acquisition (all)
cprAverage cost per referral
gross_costTotal ad spend on the Rokt platform
net_costTotal ad spend minus scrub rate
click_thru_acquisition_roasROAS for click-thru acquisitions
view_thru_acquisition_roasROAS for view-thru acquisitions
acquisition_roasROAS for all acquisitions
click_thru_conversion_roasROAS for click-thru conversions
view_thru_conversion_roasROAS for view-thru conversions
conversion_roasROAS for all conversions
view_thru_acquisitionsTotal number of view-thru acquisitions
view_thru_conversionsTotal number of view-thru conversions
acquisitionsTotal number of acquisitions
conversionsTotal number of conversions
conversions_by_conversion_timeAll conversions grouped by conversion time
copiAverage conversions per impression for acquisitions
view_thru_copiAverage conversions per impression for view-thru acquisitions
click_thru_cpa_by_conversion_timeAverage CPA for click-thru acquisitions grouped by conversion time
cost_per_impressionAverage cost per impression
custom_click_thru_conversion_rate_conversionsAverage conversion rate for click-thru conversions
unique_creativesCount of unique creatives
unique_campaignsCount of unique campaigns
unique_audiencesCount of unique audiences
unique_campaign_countriesCount of unique campaign countries
click_thru_conversion_aovAverage order value of click-thru conversions (USD)
click_thru_conversion_valueTotal value of click-thru conversions (USD)
acquisitions_valueTotal value of acquisitions (USD)
acquisition_aovAverage order value of acquisitions (USD)
conversion_valueTotal value of all conversions (USD)
conversion_aovAverage order value of conversions (USD)
view_thru_acquisitions_valueTotal value of view-thru acquisitions (USD)
view_thru_acquisition_aovAverage order value of view-thru acquisitions (USD)
view_thru_conversion_valueTotal value of view-thru conversions (USD)
view_thru_conversion_aovAverage order value of view-thru conversions (USD)
click_thru_acquisition_valueTotal value of click-thru acquisitions (USD)
click_thru_acquisition_aovAverage order value of click-thru acquisitions (USD)
Was this article helpful?
Last updated Feb 18, 2026