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

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の生成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アカウント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広告主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パートナー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