メインコンテンツまでスキップ

Query API

概要​

Rokt Query APIは、アカウントデータ、キャンペーン、およびトランザクションをクエリするための包括的で柔軟なAPIです。インタラクティブなドキュメントはこちらをご覧ください。

認証​

Rokt Query APIは、クライアント統合にOAuth 2.0アプローチを活用しています。 詳細はOAuth 2.0 Credentials Flowをご覧ください。 Query APIにアクセスするには、Rokt App IDとApp Secretを使用する必要があります。

Rokt App IDとApp Secretの生成​

  1. my.rokt.comでOne Platformにサインイン
  2. 左下のアカウントアイコンの下にあるProfile Settingsに移動
  3. Generate Personal API Credentialsセクションまでスクロールダウン
  4. アプリの名前を入力し、Generateをクリック
  5. App IDとApp Secretを安全に保管してください - App Secretには再度アクセスできません

アクセストークンの生成​

Roktは、パブリックAPIへの安全な認証のためにOAuth 2.0を使用しています。これにより、認可されたユーザーのみがデータにアクセスできるようにしています。

アクセストークンを生成するには、以下のPOSTリクエストを行います。

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"

アクセストークンは1時間後に期限切れとなり、すべてのAPIリクエストにBearerトークンとして含める必要があります。

ステップバイステップの例​

シェルコマンドを使用した完全な例を以下に示します:

# ステップ 1: 環境変数を設定します。これらをバージョン管理に保存しないでください
export ROKT_APP_ID="your_app_id"
export ROKT_APP_SECRET="your_secret"

# ステップ 2: 認証トークンを生成するために資格情報をエンコードします
export ENCODED_TOKEN=$(printf '%s' "${ROKT_APP_ID}:${ROKT_APP_SECRET}" | openssl base64 | tr -d '\n')

# Step 3: Basic認証を使用してエンコードされたトークンでOAuth2/Bearerトークンをリクエストする
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: Query APIリクエストでBearerトークンを使用する
curl -X GET "https://api.rokt.com/v1/query/accounts" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $BEARER_TOKEN"

重要な注意事項​

  • スクリプトやバージョン管理での公開を避けるために、常に環境変数を使用して資格情報を管理してください
  • printfコマンドとopenssl base64を使用することで、改行文字なしで適切にエンコードされます
  • アクセストークンは有効期限が切れるまで完全なAPIアクセスを提供するため、安全に保管してください

レート制限​

APIリクエストは、公平な使用とシステムの安定性を確保するためにレート制限されています。

エラーハンドリング​

APIは、適切なHTTPステータスコードを伴う標準化されたエラーレスポンスを返します。

アカウントAPI​

ユーザーアカウントの取得​

認証されたユーザーに関連付けられているすべてのアカウントを取得します。

説明​

このエンドポイントは、認証されたユーザーがアクセスできるすべてのアカウントのリストを返します。レスポンスには、アカウントID、名前、国、通貨、タイムゾーン情報などのアカウント詳細が含まれます。

リクエスト​

パス​
GET /v1/query/accounts
認証​

ユーザーのRokt JWTまたはエンコードされたOAuth2トークンからの有効なBearerトークンが必要です。 APIの認証方法について詳しくは、認証 ドキュメントを参照してください。

レスポンス​

以下の構造を持つアカウントオブジェクトのリストを返します:

  • accountId: アカウントの一意の識別子
  • accountName: アカウントの表示名
  • countryCode: アカウントのISO国コード
  • accountOwner: アカウントオーナーのメールアドレス（オプション）
  • accountCurrencyCode: アカウントの通貨コード
  • accountTimezone: アカウントのタイムゾーン名
  • accountTimezoneOffset: タイムゾーンのオフセット（分単位）
エラーレスポンス​
  • 401 Unauthorized: 認証に失敗しました。無効なトークンです。
  • 404 Not Found: ユーザーにはアカウントがありません
  • 500 Internal Server Error: アカウントを取得中にサーバーエラーが発生しました
レスポンス例​
[
    {
        "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
    }
]

アカウントの取得​

特定のアカウントに関する詳細情報を取得します。

説明​

このエンドポイントは、account_id パラメータで識別される特定のアカウントに関する詳細情報を返します。ユーザーは指定されたアカウントへのアクセス権限を持っている必要があります。

リクエスト​

パス​
GET /v1/query/accounts/{account_id}
パラメータ​
  • accountId (path): 取得するアカウントの一意の識別子
認証​

ユーザーのRokt JWTまたはエンコードされたOAuth2トークンからの有効なBearerトークンが必要です。 APIでの認証に関する詳細は、 認証 ドキュメントを参照してください。 ユーザーは指定されたアカウントおよびキャンペーンデータへのアクセス権限を持っている必要があります。

レスポンス​

次の構造を持つ単一のアカウントオブジェクトを返します:

  • accountId: アカウントの一意の識別子
  • accountName: アカウントの表示名
  • countryCode: アカウントのISO国コード
  • accountOwner: アカウント所有者のメールアドレス（オプション）
  • accountCurrencyCode: アカウントの通貨コード
  • accountTimezone: アカウントのタイムゾーン名
  • accountTimezoneOffset: タイムゾーンのオフセット（分単位）
エラーレスポンス​
  • 401 Unauthorized: 認証に失敗しました。トークンが無効です。
  • 403 Forbidden: ユーザーは指定されたアカウントにアクセスできません
  • 404 Not Found: 指定されたIDのアカウントは存在しません
  • 500 Internal Server Error: アカウントを取得中にサーバーエラーが発生しました
レスポンス例​
{
    "accountId": "1234567891011",
    "accountName": "Example Account 1",
    "countryCode": "US",
    "accountOwner": "user@example.com",
    "accountCurrencyCode": "USD",
    "accountTimezone": "America/New_York",
    "accountTimezoneOffset": -300
}

広告主API​

広告主レポートを取得​

指定されたアカウントの包括的なキャンペーンレポートを生成します。

説明​

このエンドポイントを使用すると、柔軟なフィルタリング、メトリクスの選択、日付範囲の指定により、キャンペーンのパフォーマンスデータをクエリできます。レスポンスには、指定した条件に基づく集計キャンペーンデータが含まれます。

リクエスト​

パス​
POST /v1/query/accounts/{account_id}/campaigns/
パラメータ​
  • account_id (パス): レポートを生成するためのアカウントの一意の識別子
リクエストボディ​

リクエストボディには、以下のフィールドを含む ReportingRequestExternal オブジェクトを含める必要があります:

パラメータ型必須説明デフォルト
timezoneVariationstringオプションレポートデータのタイムゾーン"America/New_York"
currencyCodestringオプションレポートデータの通貨コード"USD"
intervalstringオプションレポートデータの時間間隔。オプション: "day", "week", "month", "year"
startDatestring必須レポート期間の開始日をISO形式で（含む）。YYYY-MM-DDまたはYYYY-MM-DD HH:MM:SSを受け入れます
endDatestring必須レポート期間の終了日をISO形式で（除く）。YYYY-MM-DDまたはYYYY-MM-DD HH:MM:SSを受け入れます
dimensionFiltersobjectオプション特定のディメンションに適用するフィルター
metricsarray必須レポートに含めるメトリックのリスト。get_help エンドポイントからスラッグを使用
dimensionsarrayオプションデータをグループ化するディメンション。get_help エンドポイントからスラッグを使用
orderBysarrayオプション結果のソート基準。 "column" と "direction" キーの両方を受け入れます
limitintegerオプション返す結果の最大数
リクエスト例​
{
    "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"
        }
    ]
}
認証​

リクエストヘッダーには、有効なJWTベアラートークンまたはCognitoトークンが必要です。 APIでの認証に関する詳細は、 認証 ドキュメントを参照してください。 ユーザーは、指定されたアカウントおよびキャンペーンデータへのアクセス権限を持っている必要があります。

レスポンス​

ReportingResponseExternal オブジェクトを返します。内容は以下の通りです:

  • data: リクエストされたキャンペーンのメトリクスとディメンションの配列。 インターバルが指定されている場合、各オブジェクトには指定されたインターバルの開始を示す datetime フィールドが含まれます。
  • accountId: レポートが生成されたアカウントID
  • queryTimeMs: クエリの実行時間（ミリ秒）
エラーレスポンス​
  • 400 Bad Request: 無効なリクエストパラメータまたはフィルタ
  • 401 Unauthorized: 認証に失敗しました。無効なトークンです。
  • 403 Forbidden: ユーザーは指定されたアカウントへのアクセス権がありません
  • 404 Not Found: リクエストされたリソースが見つかりませんでした。 リクエストが正しいことを確認し、再試行してください。
  • 500 Internal Server Error: レポート生成中のサーバーエラー
レスポンス例​
{
    "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 /v1/query/accounts/{account_id}/campaigns/help
パラメータ​
  • account_id (path): アカウントの一意の識別子 (アクセス検証に使用されます)
認証​

ユーザーのRokt JWTまたはエンコードされたOAuth2トークンからの有効なBearerトークンが必要です。 APIでの認証に関する詳細は、 認証 ドキュメントを参照してください。 ユーザーは指定されたアカウントおよびキャンペーンデータへのアクセス権限を持っている必要があります。

レスポンス​

ReportingMetadataExternal オブジェクトを返します。内容は以下の通りです：

  • dimensions: スラッグと説明が付いたディメンションのリスト
  • metrics: スラッグと説明が付いたメトリクスのリスト
エラーレスポンス​
  • 401 Unauthorized: 認証に失敗しました。トークンが無効です。
  • 403 Forbidden: ユーザーは指定されたアカウントへのアクセス権がありません
  • 404 Not Found: リクエストされたリソースが見つかりませんでした。 リクエストが正しいことを確認して、もう一度お試しください。
  • 500 Internal Server Error: メタデータの取得中にサーバーエラーが発生しました
レスポンスの例​
{
  "dimensions": [
      {
          "slug": "age_range",
          "description": "ユーザーの年齢層"
      },
      {
          "slug": "campaign_id",
          "description": "キャンペーンのID"
      },
      {
          "slug": "creative_id",
          "description": "クリエイティブのID"
      },
      {
          "slug": "device",
          "description": "ユーザーのデバイス"
      },
  ],
  "metrics": [
      {
          "slug": "impressions",
          "description": "広告のインプレッション数"
      },
      {
          "slug": "referrals",
          "description": "広告へのポジティブなエンゲージメント数"
      },
      {
          "slug": "clickthru_acquisitions",
          "description": "広告のクリックスルー獲得数。獲得とは、エンゲージメントイベントに続く最初のコンバージョンを表します。"
      },
      {
          "slug": "cpa",
          "description": "広告の獲得単価 (Cost per Acquisition)"
      },
      {
          "slug": "gross_cost",
          "description": "広告の総コスト (支出)"
      },
  ]
}

パートナーAPI​

パートナーレポートの取得​

指定されたアカウントの包括的なトランザクションレポートを生成します。

説明​

このエンドポイントを使用すると、柔軟なフィルタリング、メトリクスの選択、日付範囲の指定を用いてトランザクションデータをクエリできます。レスポンスには、指定された条件に基づいた集計トランザクションデータが含まれます。

リクエスト​

パス​
POST /v1/query/accounts/{account_id}/transactions
パラメータ​
  • account_id (path): レポートを生成するアカウントの一意の識別子
リクエストボディ​

リクエストボディには、以下のフィールドを含むReportingRequestExternalオブジェクトを含める必要があります:

パラメータ型必須説明デフォルト
timezoneVariationstringオプションレポートデータのタイムゾーン"America/New_York"
currencyCodestringオプションレポートデータの通貨コード"USD"
intervalstringオプションレポートデータの時間間隔。オプション: "day", "week", "month", "year"
startDatestring必須レポート期間の開始日をISO形式で指定（含む）。YYYY-MM-DDまたはYYYY-MM-DD HH:MM:SSを受け入れます
endDatestring必須レポート期間の終了日をISO形式で指定（除く）。YYYY-MM-DDまたはYYYY-MM-DD HH:MM:SSを受け入れます
dimensionFiltersobjectオプション特定のディメンションに適用するフィルタ
metricsarray必須レポートに含めるメトリクスのリスト。get_helpエンドポイントからスラッグを使用
dimensionsarrayオプションデータをグループ化するディメンション。get_helpエンドポイントからスラッグを使用
orderBysarrayオプション結果のソート基準。「column」と「direction」キーの両方を受け入れます
limit整数任意返される結果の最大数
リクエスト例​
{
    "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"
        }
    ]
}
認証​

リクエストヘッダーには、有効なJWTベアラートークンまたはCognitoトークンが必要です。 APIでの認証に関する詳細は、 認証 ドキュメントをご覧ください。 ユーザーは、指定されたアカウントおよびトランザクションデータへのアクセス権を持っている必要があります。

レスポンス​

ReportingResponseExternal オブジェクトを返します。内容は以下の通りです：

  • data: 要求されたトランザクションメトリクスとディメンションの配列。 インターバルが指定されている場合、各オブジェクトには指定されたインターバルの開始を示す datetime フィールドが含まれます。
  • accountId: レポートが生成されたアカウントID
  • queryTimeMs: クエリの実行時間（ミリ秒）
エラーレスポンス​
  • 400 Bad Request: 無効なリクエストパラメータまたはフィルタ
  • 401 Unauthorized: 認証に失敗しました。無効なトークン。
  • 403 Forbidden: 指定されたアカウントへのアクセス権がありません
  • 404 Not Found: リクエストされたリソースが見つかりませんでした。 リクエストが正しいことを確認し、再試行してください。
  • 500 Internal Server Error: レポート生成中のサーバーエラー
レスポンス例​
{
    "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 /v1/query/accounts/{account_id}/transactions/help
パラメータ​
  • account_id (パス): アカウントのユニークな識別子 (アクセス検証に使用)
認証​

ユーザーのRokt JWTまたはエンコードされたOAuth2トークンからの有効なBearerトークンが必要です。 APIでの認証に関する詳細は、 認証 ドキュメントを参照してください。 ユーザーは指定されたアカウントとトランザクションデータへのアクセス権限を持っている必要があります。

レスポンス​

ReportingMetadataExternalオブジェクトを返します。含まれるのは:

  • dimensions: スラッグと定義を含むディメンションのリスト
  • metrics: スラッグと定義を含むメトリクスのリスト
エラーレスポンス​
  • 401 Unauthorized: 認証に失敗しました。無効なトークンです。
  • 403 Forbidden: ユーザーは指定されたアカウントへのアクセス権がありません
  • 404 Not Found: リクエストされたリソースが見つかりませんでした。 リクエストが正しいことを確認し、再試行してください。
  • 500 Internal Server Error: メタデータの取得中にサーバーエラーが発生しました
レスポンスの例​
{
    "dimensions": [
        {
            "slug": "age_range",
            "description": "ユーザーの年齢範囲"
        },
        {
            "slug": "display_type",
            "description": "広告が表示されたディスプレイの種類"
        },
        {
            "slug": "page_type",
            "description": "ユーザーが閲覧していたページの種類"
        },
        {
            "slug": "device",
            "description": "ユーザーのデバイス"
        },
    ],
    "metrics": [
        {
            "slug": "transactions",
            "description": "トランザクションの総数"
        },
        {
            "slug": "rokt_transactions_per_transaction",
            "description": "Roktによって処理されたトランザクションの総数"
        },
        {
            "slug": "impressions",
            "description": "広告インプレッションの総数"
        },
        {
            "slug": "page_transactions",
            "description": "ページごとに処理されたトランザクションの総数"
        },
        {
            "slug": "layout_impressions",
            "description": "レイアウトごとに処理された広告インプレッションの総数"
        },
    ]
}
この記事は役に立ちましたか？
Last updated Oct 29, 2025