非同期アナリティクス

GET stats/jobs/accounts/:account_id

現在のアカウントの一部またはすべての非同期アナリティクスジョブの詳細を取得します。

ジョブが正常に完了すると("status": "SUCCESS")、urlパラメーターで返されるURLにあるファイルをダウンロードしてデータを取得できます。これらの結果ファイルは、転送を最適化するために圧縮(gzip)されており、アクセスする前に解凍する必要があります。

: このエンドポイントが返すHTTP応答ヘッダーは次のとおりです。

  • X-Concurrent-Job-Limit: 特定の時点で処理状態にある可能性のあるジョブの最大数。
  • X-Concurrent-Job-Limit-Remaining: 現在処理中のジョブ数を考慮した作成可能な数。

リソースURL

https://ads-api.x.com/10/stats/jobs/accounts/:account_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 200
最小、最大: 11000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow

job_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的のジョブのみに設定します。最大200件のIDを指定できます。

タイプ: 長整数型

例: 883787505404747776

リクエストの例

GET https://ads-api.x.com/10/stats/jobs/accounts/18ce54d4x5t?job_ids=883787505404747776

応答の例

{
  "request": {
    "params": {
      "job_ids": [
        883787505404747776
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "start_time": "2017-05-19T07:00:00Z",
      "segmentation_type": null,
      "url": "https://ton.twimg.com/advertiser-api-async-analytics/hMk_CPWYqCAYY99gWzylwNJe26HgVm9Iji0wFiuEXbE74bjWsyTtop49MpL-QXO5bhebBZwFhvK9GyNs4gSnfoCG8wdSLmnhKZ0hj7PezoiQggj9AywMDHCMwq3gGHHv.json.gz",
      "id_str": "883787505404747776",
      "entity_ids": [
        "8u94t"
      ],
      "end_time": "2017-05-26T07:00:00Z",
      "country": null,
      "placement": "ALL_ON_TWITTER",
      "id": 883787505404747776,
      "expires_at": "2017-07-10T20:38:57Z",
      "status": "SUCCESS",
      "granularity": "DAY",
      "entity": "LINE_ITEM",
      "created_at": "2017-07-08T20:38:55Z",
      "platform": null,
      "updated_at": "2017-07-08T20:38:57Z",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  ]
}

POST stats/jobs/accounts/:account_id

現在のアカウントに非同期アナリティクスジョブを作成します。

セグメント化されていないクエリには、90日の最大時間範囲(end_time - start_time)が許可されます。セグメント化されたクエリの場合、最大時間範囲は45日です。

job_idが返されます。これをGET stats/jobs/accounts/:account_idリクエストで使用すると、ジョブが処理をいつ終了したかを確認できます。

ジョブが正常に完了すると("status": "SUCCESS")、urlパラメーターで返されるURLにあるファイルをダウンロードしてデータを取得できます。これらの結果ファイルは、転送を最適化するために圧縮(gzip)されており、アクセスする前に解凍する必要があります。

: このエンドポイントが返すHTTP応答ヘッダーは次のとおりです。

  • X-Concurrent-Job-Limit: 特定の時点で処理状態にある可能性のあるジョブの最大数。
  • X-Concurrent-Job-Limit-Remaining: 現在処理中のジョブ数を考慮した作成可能な数。

リソースURL

https://ads-api.x.com/10/stats/jobs/accounts/:account_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

end_time
必須

取得するデータの範囲を、ISO 8601で表される、指定の終了時間に設定します。

: 時間の単位(0分0秒)で表す必要があります。

タイプ: 文字列

例: 2017-05-26T07:00:00Z

entity
必須

データを取得するエンティティのタイプ。

タイプ: 列挙

使用可能な値: ACCOUNTCAMPAIGNFUNDING_INSTRUMENTLINE_ITEMORGANIC_TWEETPROMOTED_ACCOUNTPROMOTED_TWEETMEDIA_CREATIVE

entity_ids
必須

データを取得する特定のエンティティ。エンティティIDのカンマ区切りのリストを指定します。

: 最大20件のエンティティIDを指定できます。

タイプ: 文字列

例: 8u94t

granularity
必須

取得するデータの詳細度を指定します。

タイプ: 列挙

使用可能な値: DAYHOURTOTAL

metric_groups
必須

返される特定のメトリック。メトリックグループのカンマ区切りのリストを指定します。詳細については、「メトリックとセグメント化」を参照してください。

: MOBILE_CONVERSIONデータは個別にリクエストする必要があります。

タイプ: 列挙

使用可能な値: BILLINGENGAGEMENTLIFE_TIME_VALUE_MOBILE_CONVERSIONMEDIAMOBILE_CONVERSIONVIDEOWEB_CONVERSION

placement
必須

取得するデータの範囲を、特定の配置に設定します。

: 使用できる値は、リクエストごとに1つのみです。TwitterとTwitterオーディエンスプラットフォームプレースメントの両方を持つエンティティの場合は、プレースメントの値ごとに個別のリクエストが必要です。

タイプ: 列挙

使用可能な値: ALL_ON_TWITTERPUBLISHER_NETWORK

start_time
必須

取得するデータの範囲を、ISO 8601で表される、指定の開始時間に設定します。

: 時間の単位(0分0秒)で表す必要があります。

タイプ: 文字列

例: 2017-05-19T07:00:00Z

country
必須の場合あり

国。これはGET targeting_criteria/locationsエンドポイントの応答のtargeting_valueです。

: segmentation_typeMETROSPOSTAL_CODESREGIONSのいずれかの場合は必須です。

タイプ: 文字列

例: 96683cc9126741d1

platform
必須の場合あり

プラットフォームのタイプ。

: segmentation_typeDEVICESまたはPLATFORM_VERSIONSのいずれかの場合は必須です。

タイプ: 整数

例: 「GET targeting_criteria/platforms」を参照してください

segmentation_type
任意

取得するデータのセグメント方法を指定します。

: 使用できる値は、リクエストごとに1つのみです。

: メディアクリエイティブまたはオーガニックツイートのアナリティクスをリクエストするときは、セグメント化はサポートされません。

タイプ: 列挙

使用可能な値: 「メトリックとセグメント化」を参照してください。

リクエストの例

POST https://ads-api.x.com/10/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=DAY&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT

応答の例

{
  "request": {
    "params": {
      "start_time": "2017-05-19T07:00:00Z",
      "entity_ids": [
        "8u94t"
      ],
      "account_id": "18ce54d4x5t",
      "end_time": "2017-05-26T07:00:00Z",
      "placement": "ALL_ON_TWITTER",
      "granularity": "DAY",
      "entity": "LINE_ITEM",
      "metric_groups": [
        "ENGAGEMENT"
      ]
    }
  },
  "data": {
    "start_time": "2017-05-19T07:00:00Z",
    "segmentation_type": null,
    "url": null,
    "id_str": "883787505404747776",
    "entity_ids": [
      "8u94t"
    ],
    "end_time": "2017-05-26T07:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": 883787505404747776,
    "expires_at": null,
    "status": "PROCESSING",
    "granularity": "DAY",
    "entity": "LINE_ITEM",
    "created_at": "2017-07-08T20:38:55Z",
    "platform": null,
    "updated_at": "2017-07-08T20:38:55Z",
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}

DELETE stats/jobs/accounts/:account_id/:job_id

指定した広告アカウントの非同期アナリティクスジョブをキャンセルします。

: キャンセルできるのは、PROCESSINGジョブのみです。

リソースURL

https://ads-api.x.com/10/stats/jobs/accounts/:account_id/:job_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

job_id
必須

リクエスト内で操作するジョブへの参照。

タイプ: 長整数型

例: 823634888955809793

リクエストの例

DELETE https://ads-api.x.com/10/stats/jobs/accounts/18ce54d4x5t/823634888955809793

応答の例

{
  "request": {
    "params": {
      "job_id": 823634888955809793,
      "account_id": "18ce54d4x5t"
    }
  },
  "data_type": "job",
  "data": {
    "start_time": "2016-10-25T07:00:00Z",
    "segmentation_type": "AGE",
    "url": null,
    "id_str": "823634888955809793",
    "entity_ids": [
      "6c62d"
    ],
    "end_time": "2016-12-05T08:00:00Z",
    "country": null,
    "placement": "ALL_ON_TWITTER",
    "id": 823634888955809793,
    "expires_at": null,
    "status": "CANCELLED",
    "granularity": "DAY",
    "entity": "LINE_ITEM",
    "created_at": "2017-01-23T20:53:54Z",
    "platform": null,
    "updated_at": "2017-01-23T20:53:54Z",
    "metric_groups": [
      "ENGAGEMENT"
    ]
  }
}