Query API

Vue d'ensemble

L'API Rokt Query est une API complète et flexible pour interroger les données de compte, les campagnes et les transactions. Consultez notre documentation interactive ici.

Authentification

L'API Rokt Query utilise l'approche OAuth 2.0 pour l'intégration client. Voir le Flux d'Informations d'Identification OAuth 2.0 pour plus de détails. Vous devez utiliser votre ID d'application Rokt et votre Secret d'application pour accéder à l'API Query.

Génération d'un ID d'application Rokt et d'un Secret d'application

1. Connectez-vous à One Platform sur my.rokt.com
2. Accédez à Paramètres du profil sous l'icône de votre compte en bas à gauche
3. Faites défiler jusqu'à la section Générer des informations d'identification API personnelles
4. Entrez le nom de votre application et cliquez sur Générer
5. Stockez l'ID d'application et le Secret d'application en toute sécurité - vous n'aurez plus accès au Secret d'application

Génération d'un jeton d'accès

Rokt utilise OAuth 2.0 pour une authentification sécurisée à nos API publiques. Cela garantit que seuls les utilisateurs autorisés peuvent accéder à leurs données.

Pour générer un jeton d'accès, effectuez la requête POST suivante.

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"

Le jeton d'accès expire après une heure et doit être inclus comme un jeton Bearer dans toutes les requêtes API.

Exemple étape par étape

Voici un exemple complet utilisant des commandes shell :

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

Notes importantes

• Utilisez toujours des variables d'environnement pour les informations d'identification afin d'éviter de les exposer dans les scripts ou le contrôle de version
• La commande printf avec openssl base64 assure un encodage correct sans caractères de nouvelle ligne
• Stockez le jeton d'accès en toute sécurité car il fournit un accès complet à l'API jusqu'à expiration

Limitation de débit

Les requêtes API sont limitées en débit pour assurer une utilisation équitable et la stabilité du système.

Gestion des erreurs

L'API renvoie des réponses d'erreur standardisées avec des codes d'état HTTP appropriés.

APIs de compte

Obtenir les comptes utilisateur

Récupérez tous les comptes associés à l'utilisateur authentifié.

Description

Ce point de terminaison renvoie une liste de tous les comptes auxquels l'utilisateur authentifié a accès. La réponse inclut des détails sur le compte tels que l'ID du compte, le nom, le pays, la devise, et les informations de fuseau horaire.

Requête

Chemin

GET /v1/query/accounts

Authentification

Nécessite un jeton Bearer valide provenant d'un JWT Rokt de l'utilisateur ou d'un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la Documentation d'authentification .

Réponse

Renvoie une liste d'objets de compte avec la structure suivante :

• accountId : Identifiant unique pour le compte
• accountName : Nom d'affichage du compte
• countryCode : Code pays ISO pour le compte
• accountOwner : Adresse e-mail du propriétaire du compte (optionnel)
• accountCurrencyCode : Code de devise pour le compte
• accountTimezone : Nom du fuseau horaire pour le compte
• accountTimezoneOffset : Décalage du fuseau horaire en minutes

Réponses d'erreur

• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 404 Not Found : L'utilisateur n'a pas de comptes
• 500 Internal Server Error : Erreur du serveur lors de la récupération des comptes

Exemple de réponse

[
    {
        "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
    }
]

Obtenir le compte

Récupérer des informations détaillées pour un compte spécifique.

Description

Ce point de terminaison renvoie des informations détaillées sur un compte spécifique identifié par le paramètre account_id. L'utilisateur doit avoir des autorisations d'accès au compte spécifié.

Requête

Chemin

GET /v1/query/accounts/{account_id}

Paramètres

• accountId (chemin) : L'identifiant unique du compte à récupérer

Authentification

Nécessite un jeton Bearer valide provenant d'un JWT Rokt de l'utilisateur ou d'un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la Documentation d'authentification . L'utilisateur doit avoir des autorisations d'accès au compte spécifié et aux données de campagne.

Réponse

Renvoie un objet de compte unique avec la structure suivante :

• accountId : Identifiant unique pour le compte
• accountName : Nom d'affichage du compte
• countryCode : Code pays ISO pour le compte
• accountOwner : Adresse e-mail du propriétaire du compte (optionnel)
• accountCurrencyCode : Code de devise pour le compte
• accountTimezone : Nom du fuseau horaire pour le compte
• accountTimezoneOffset : Décalage du fuseau horaire en minutes

Réponses d'erreur

• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
• 404 Not Found : Le compte avec l'ID spécifié n'existe pas
• 500 Internal Server Error : Erreur du serveur lors de la récupération du compte

Exemple de Réponse

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

APIs Annonceur

Obtenir le Rapport Annonceur

Générez un rapport de campagne complet pour le compte spécifié.

Description

Ce point de terminaison vous permet de requêter les données de performance de campagne avec un filtrage flexible, une sélection de métriques et une spécification de plage de dates. La réponse inclut des données de campagne agrégées basées sur vos critères spécifiés.

Requête

Chemin

POST /v1/query/accounts/{account_id}/campaigns/

Paramètres

• account_id (chemin) : L'identifiant unique du compte pour lequel générer le rapport

Corps de la Requête

Le corps de la requête doit contenir un objet ReportingRequestExternal avec les champs suivants :

Paramètre	Type	Requis	Description	Défaut
timezoneVariation	chaîne	optionnel	Fuseau horaire pour les données du rapport	"America/New_York"
currencyCode	chaîne	optionnel	Code de devise pour les données du rapport	"USD"
interval	chaîne	optionnel	Intervalle de temps pour les données du rapport. Options : "day", "week", "month", "year"
startDate	chaîne	requis	Date de début pour la période du rapport au format ISO (inclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
endDate	chaîne	requis	Date de fin pour la période du rapport au format ISO (exclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
dimensionFilters	objet	optionnel	Filtres à appliquer à des dimensions spécifiques
metrics	tableau	requis	Liste des métriques à inclure dans le rapport. Utilisez les slugs de l'endpoint get_help
dimensions	tableau	optionnel	Dimensions pour regrouper les données. Utilisez les slugs de l'endpoint get_help
orderBys	tableau	optionnel	Critères de tri pour les résultats. Accepte les clés "column" et "direction"
limit	entier	optionnel	Nombre maximum de résultats à retourner

Exemple de Requête

{
    "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"
        }
    ]
}

Authentification

Nécessite soit un jeton JWT Bearer valide, soit un jeton Cognito dans les en-têtes de la requête. Pour plus d'informations sur l'authentification avec notre API, consultez la Authentification documentation. L'utilisateur doit avoir des permissions d'accès aux données du compte et de la campagne spécifiés.

Réponse

Retourne un objet ReportingResponseExternal contenant :

• data : Tableau des métriques et dimensions de campagne demandées. Si un intervalle est fourni, chaque objet contiendra un champ datetime indiquant le début de l'intervalle fourni.
• accountId : L'ID du compte pour lequel le rapport a été généré
• queryTimeMs : Temps d'exécution de la requête en millisecondes

Réponses d'Erreur

• 400 Bad Request : Paramètres de requête ou filtres invalides
• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
• 404 Not Found : La ressource demandée n'a pas été trouvée. Veuillez valider que votre requête est correcte et réessayez.
• 500 Internal Server Error : Erreur du serveur lors de la génération du rapport

Exemple de Réponse

{
    "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
    }

Obtenir de l'Aide

Récupérer les métriques et dimensions disponibles pour le reporting de campagne.

Description

Ce point de terminaison retourne des métadonnées sur les options de reporting disponibles, y compris quelles métriques et dimensions peuvent être utilisées ensemble, leurs noms d'affichage, et toute option de configuration supplémentaire.

Requête

Chemin

GET /v1/query/accounts/{account_id}/campaigns/help

Paramètres

• account_id (chemin) : L'identifiant unique du compte (utilisé pour la validation d'accès)

Authentification

Nécessite un jeton Bearer valide d'un JWT Rokt de l'utilisateur ou un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la Authentification documentation. L'utilisateur doit avoir des permissions d'accès aux données du compte et de la campagne spécifiés.

Réponse

Retourne un objet ReportingMetadataExternal contenant :

• dimensions : Liste des dimensions avec leurs slugs et descriptions
• metrics : Liste des métriques avec leurs slugs et descriptions

Réponses d'Erreur

• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
• 404 Not Found : La ressource demandée n'a pas été trouvée. Veuillez valider que votre requête est correcte et réessayez.
• 500 Internal Server Error : Erreur du serveur lors de la récupération des métadonnées

Exemple de Réponse

{
  "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"
      },
  ]
}

APIs Partenaires

Obtenir le Rapport Partenaire

Générez un rapport de transaction complet pour le compte spécifié.

Description

Ce point de terminaison vous permet d'interroger les données de transaction avec un filtrage flexible, une sélection de métriques et une spécification de plage de dates. La réponse inclut des données de transaction agrégées basées sur vos critères spécifiés.

Requête

Chemin

POST /v1/query/accounts/{account_id}/transactions

Paramètres

• account_id (chemin) : L'identifiant unique du compte pour lequel générer le rapport

Corps de la Requête

Le corps de la requête doit contenir un objet ReportingRequestExternal avec les champs suivants :

Paramètre	Type	Requis	Description	Par Défaut
timezoneVariation	chaîne	optionnel	Fuseau horaire pour les données du rapport	"America/New_York"
currencyCode	chaîne	optionnel	Code de devise pour les données du rapport	"USD"
interval	chaîne	optionnel	Intervalle de temps pour les données du rapport. Options : "day", "week", "month", "year"
startDate	chaîne	requis	Date de début pour la période du rapport au format ISO (inclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
endDate	chaîne	requis	Date de fin pour la période du rapport au format ISO (exclus). Accepte YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS
dimensionFilters	objet	optionnel	Filtres à appliquer à des dimensions spécifiques
metrics	tableau	requis	Liste des métriques à inclure dans le rapport. Utilisez les slugs de l'endpoint get_help
dimensions	tableau	optionnel	Dimensions pour regrouper les données. Utilisez les slugs de l'endpoint get_help
orderBys	tableau	optionnel	Critères de tri pour les résultats. Accepte les clés "column" et "direction"
limit	entier	optionnel	Nombre maximum de résultats à retourner

Exemple de Requête

{
    "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"
        }
    ]
}

Authentification

Nécessite soit un jeton JWT Bearer valide, soit un jeton Cognito dans les en-têtes de la requête. Pour plus d'informations sur l'authentification avec notre API, consultez la Documentation d'Authentification. L'utilisateur doit avoir des permissions d'accès au compte et aux données de transaction spécifiés.

Réponse

Retourne un objet ReportingResponseExternal contenant :

• data : Tableau des métriques et dimensions de transaction demandées. Si un intervalle est fourni, chaque objet contiendra un champ datetime indiquant le début de l'intervalle fourni.
• accountId : L'ID du compte pour lequel le rapport a été généré
• queryTimeMs : Temps d'exécution de la requête en millisecondes

Réponses d'Erreur

• 400 Bad Request : Paramètres ou filtres de requête invalides
• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
• 404 Not Found : La ressource demandée n'a pas été trouvée. Veuillez valider que votre requête est correcte et réessayez.
• 500 Internal Server Error : Erreur serveur lors de la génération du rapport

Exemple de Réponse

{
    "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
    }

Obtenir de l'Aide

Récupérer les métriques et dimensions disponibles pour le reporting de transactions.

Description

Ce point de terminaison retourne des métadonnées sur les options de reporting disponibles, incluant quelles métriques et dimensions peuvent être utilisées ensemble, leurs noms d'affichage, et toutes options de configuration supplémentaires.

Requête

Chemin

GET /v1/query/accounts/{account_id}/transactions/help

Paramètres

• account_id (chemin) : L'identifiant unique du compte (utilisé pour la validation d'accès)

Authentification

Nécessite un jeton Bearer valide à partir d'un JWT Rokt de l'utilisateur ou d'un jeton OAuth2 encodé. Pour plus d'informations sur l'authentification avec notre API, consultez la Documentation d'Authentification. L'utilisateur doit avoir des permissions d'accès au compte et aux données de transaction spécifiés.

Réponse

Retourne un objet ReportingMetadataExternal contenant :

• dimensions : Liste des dimensions avec leurs slugs et définitions
• metrics : Liste des métriques avec leurs slugs et définitions

Réponses d'Erreur

• 401 Unauthorized : Échec de l'authentification. Jeton invalide.
• 403 Forbidden : L'utilisateur n'a pas accès au compte spécifié
• 404 Not Found : La ressource demandée n'a pas été trouvée. Veuillez valider que votre requête est correcte et réessayez.
• 500 Internal Server Error : Erreur serveur lors de la récupération des métadonnées

Exemple de Réponse

{
    "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"
        },
    ]
}

Points de Données Disponibles

Les dimensions et métriques suivantes sont disponibles pour utilisation avec l'API de requête. Utilisez les points de terminaison Obtenir de l'Aide pour les campagnes ou les transactions afin de récupérer la liste exacte disponible pour votre compte. Les slugs ci-dessous sont utilisés dans les corps de requête pour dimensions, metrics, dimensionFilters, et orderBys.

Dimensions

Slug	Description
age_range	Tranche d'âge de l'utilisateur
audience_name	Nom de l'audience
advertiser_id	ID de l'annonceur
campaign_id	ID de la campagne
campaign_name	Nom de la campagne
campaign_objective	Objectif de la campagne
campaign_country	Pays de la campagne
creative_id	ID de la création
creative_name	Nom de la création
device	Appareil de l'utilisateur
gender	Genre de l'utilisateur
partner_sub_vertical	Sous-verticale du partenaire
partner_vertical	Verticale du partenaire
rank	Rang du placement publicitaire
user_country	Pays de l'utilisateur
rank	Rang du placement publicitaire
contains_lookalike_audience	Si la campagne contient une audience similaire
customer_interactivity	Segment d'interactivité client
platform_type	Environnement d'application à travers lequel un Rokt Layout est rendu

Métriques

Slug	Description
impressions	Nombre total d'impressions publicitaires
referral_rate	Nombre total de références par impression
referrals	Nombre total d'engagements positifs sur les publicités
click_thru_acquisitions	Acquisitions par clic groupées par temps de campagne (première conversion après engagement)
click_thru_acquisitions_by_conversion_time	Acquisitions par clic groupées par temps de conversion
view_thru_acquisitions_by_conversion_time	Acquisitions par vue groupées par temps de conversion
acquisitions_by_conversion_time	Toutes les acquisitions groupées par temps de conversion
conversion_amount_fill_rate	Taux de remplissage moyen du montant de conversion pour les conversions
click_thru_conversion_rate	Taux de conversion moyen pour les conversions par clic
view_thru_conversion_rate	Taux de conversion moyen pour les conversions par vue
conversion_rate	Taux de conversion moyen pour toutes les conversions
click_thru_conversions	Nombre total de conversions par clic
click_thru_conversions_by_conversion_time	Conversions par clic groupées par temps de conversion
view_thru_conversions_by_conversion_time	Conversions par vue groupées par temps de conversion
click_thru_copi	Moyenne des conversions par clic par impression publicitaire
click_thru_cpa	Coût moyen par acquisition pour les acquisitions par clic
view_thru_cpa	Coût moyen par acquisition pour les acquisitions par vue
cpa	Coût moyen par acquisition (toutes)
cpr	Coût moyen par référence
gross_cost	Dépenses publicitaires totales sur la plateforme Rokt
net_cost	Dépenses publicitaires totales moins le taux de nettoyage
click_thru_acquisition_roas	ROAS pour les acquisitions par clic
view_thru_acquisition_roas	ROAS pour les acquisitions par vue
acquisition_roas	ROAS pour toutes les acquisitions
click_thru_conversion_roas	ROAS pour les conversions par clic
view_thru_conversion_roas	ROAS pour les conversions par vue
conversion_roas	ROAS pour toutes les conversions
view_thru_acquisitions	Nombre total d'acquisitions par vue
view_thru_conversions	Nombre total de conversions par vue
acquisitions	Nombre total d'acquisitions
conversions	Nombre total de conversions
conversions_by_conversion_time	Toutes les conversions groupées par temps de conversion
copi	Moyenne des conversions par impression pour les acquisitions
view_thru_copi	Moyenne des conversions par impression pour les acquisitions par vue
click_thru_cpa_by_conversion_time	CPA moyen pour les acquisitions par clic groupées par temps de conversion
cost_per_impression	Coût moyen par impression
custom_click_thru_conversion_rate_conversions	Taux de conversion moyen pour les conversions par clic
unique_creatives	Nombre de créations uniques
unique_campaigns	Nombre de campagnes uniques
unique_audiences	Nombre d'audiences uniques
unique_campaign_countries	Nombre de pays de campagne uniques
click_thru_conversion_aov	Valeur moyenne des commandes des conversions par clic (USD)
click_thru_conversion_value	Valeur totale des conversions par clic (USD)
acquisitions_value	Valeur totale des acquisitions (USD)
acquisition_aov	Valeur moyenne des commandes des acquisitions (USD)
conversion_value	Valeur totale de toutes les conversions (USD)
conversion_aov	Valeur moyenne des commandes des conversions (USD)
view_thru_acquisitions_value	Valeur totale des acquisitions par vue (USD)
view_thru_acquisition_aov	Valeur moyenne des commandes des acquisitions par vue (USD)
view_thru_conversion_value	Valeur totale des conversions par vue (USD)
view_thru_conversion_aov	Valeur moyenne des commandes des conversions par vue (USD)
click_thru_acquisition_value	Valeur totale des acquisitions par clic (USD)
click_thru_acquisition_aov	Valeur moyenne des commandes des acquisitions par clic (USD)