キャンペーン管理

​

Advertiser API

この一連のAPIを利用することで、X上のキャンペーンや広告をプログラムからスケジュールし、管理できます。

​

何をプロモーションできるか

​

Promoted Ads

• Promoted Ads (プロモーション広告) は、より幅広いユーザー層にリーチしたい、あるいは既存のフォロワーからのエンゲージメントを喚起したい広告主が購入する通常の広告です。
• Promoted Ads は、広告主が X 上での掲載に対して支払っている場合、「Promoted」として明確にラベル表示されます。それ以外の点では、Promoted Ads は通常の広告と同様に機能し、リポスト、返信、いいねなどが可能です。通常の配信ルールが適用され、POST statuses/update を使って作成されます。
• 「Promoted-only」ツイートは、POST accounts/:account_id/tweet を使用して作成され、Promoted Tweets キャンペーンで利用できますが、フォロワーには配信されず、公開タイムラインにも表示されません。特定アカウントの Promoted-only ツイートのリストを取得するには、GET accounts/:account_id/scoped_timeline を使用してください。

​

プロモアカウント

• プロモアカウントは「おすすめユーザー」の一部であり、ユーザーが現在フォローしていないが、興味を持つ可能性のあるアカウントをおすすめする機能です。プロモアカウントを利用することで、ユーザーが楽しめる可能性のある、さらに幅広いアカウントを紹介できます。
• タイムライン向けのプロモアカウントでは、プロモツイートをプロモアカウントキャンペーンに紐付けて、ユーザーのタイムラインに表示します。

プロモトレンドは Ads API では利用できません。

​

キャンペーンと広告グループ (ラインアイテム)

キャンペーンは、広告の配信スケジュールと予算を定義します。広告主は 1 日あたりの予算と総予算を指定します。キャンペーンは特定の開始時刻と終了時刻に紐づけることも、予算が消化されるまで継続的に配信することもできます。予算は広告アカウントの Funding Instruments のいずれかから支出されます。キャンペーン識別子 (:campaign_id) は、X Ads UI に表示される 10 進数の値を 36 進数表現にしたものです。

広告アカウントごとに、アクティブなキャンペーンは最大 200 件までに制限されています。この上限は、広告主からの依頼に基づき、担当の X アカウントマネージャーによって手動で 4,000 件まで引き上げることができます。キャンペーンは、終了時刻に達するか削除されるまでアクティブと見なされます。一時停止中のキャンペーンも、指定された終了時刻に達するまではアクティブと見なされます。

ラインアイテムは、キャンペーンで定義された予算を消化します。ラインアイテムは、エンゲージメント単価の入札額、プロモーション対象のツイートまたはアカウント、およびターゲティングルールをまとめて指定します。

​

アナリティクス

X Ads API には、広告パフォーマンスを追跡および最適化するための一連のアナリティクス用エンドポイントが用意されています。詳細については、「Analytics」および「Analytics Best Practices」を参照してください。

課金指標については、イベント発生から 3 日後までデータが確定しない場合があります。それまでは、そのデータは暫定値として扱う必要があります。最終的な課金対象の数値は、必ず暫定値以下になります。課金対象の数値は、スパムや関連する低品質トラフィックを補正した結果の値です。時間に関するその他の考慮事項については、「Timezones」を参照してください。

​

キャンペーンの作成手順

次の例では、twurl を使用して App とユーザーのインストール、設定、認可を済ませていることを前提とします。twurl は cURL と同様のコマンドラインツールで、X の OAuth 認証を適切に処理します。twurl は Ads API (および REST API) の機能を迅速にテストおよびデバッグするのに便利なツールです。リクエストとレスポンスのヘッダー全体を確認するには、-t を使用して呼び出しをトレースします。これは cURL の -v オプションとおおよそ同等です。

この例では、キーワードでターゲティングされる Promoted Ads キャンペーンを作成します。

1. アカウント ID を取得します。

twurl -H ads-api.x.com /9/accounts/

{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Test account for @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}

2. ファンディングインストゥルメントの id を取得します。

前のコマンドで取得したアカウント id を使用して、GET accounts/:account_id/funding_instruments API を呼び出します。

twurl -H ads-api.x.com /9/accounts/xxxxxx/funding_instruments

{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}

3. キャンペーンを作成し、ファンディングインストゥルメントに関連付けます。

キャンペーンの開始日時と予算を指定します。この例では、予算を500ドル、1日あたりの上限額を50ドルとします。

twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=My First Campaign&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /9/accounts/xxxxxx/campaigns

{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "My First Campaign",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "My First Campaign",
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4. キャンペーンに関連付けられたラインアイテムを作成します。

キャンペーン id を取得したので、それに関連付けるラインアイテムを作成できるようになりました。ラインアイテムは、入札価格、ターゲティング、キャンペーンにおける実際のクリエイティブ部分をまとめたものです。このラインアイテムでは、$1.50 の入札でツイートをプロモーションします。

twurl -H ads-api.x.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=ENGAGEMENTS&entity_status=PAUSED" /9/accounts/xxxxxxx/line_items

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "azjx",
    "entity_status": "PAUSED",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:00Z",
    "updated_at": "2015-02-09T00:00:00Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "92ph",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 1500000,
      "product_type": "PROMOTED_TWEETS",
      "entity_status": "PAUSED",
      "account_id": "xxxxxxx",
      "campaign_id": "92ph"
    }
  }
}

5. ラインアイテムに紐づくターゲティングプロファイルを作成します。

ラインアイテムを作成したので、ターゲティング条件を割り当てることができます。ここでは、サンフランシスコ・ベイエリアのロケーションにおいて、フレーズキーワード「grumpy cat」をターゲットにします。これには、ロケーション id の取得と、targeting_criteria への POST リクエストを 2 回行う必要があります。

twurl -H ads-api.x.com "/9/targeting_criteria/locations?location_type=CITIES&q=San Francisco"

{
  "data": [
    {
      "name": "San Francisco-Oakland-San Jose CA, US",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}

twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}

twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /9/accounts/xxxxxx/targeting_criteria

{
  "data": {
    "created_at": "2015-02-09T00:00:20Z",
    "deleted": false,
    "id": "2u3bd",
    "line_item_id": "yyyy",
    "name": "grumpy cat",
    "targeting_type": "PHRASE_KEYWORD",
    "targeting_value": "grumpy cat",
    "updated_at": "2013-05-30T18:05:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "PHRASE_KEYWORD",
      "targeting_value": "grumpy cat"
    }
  }
}

6. 最後に、ラインアイテムの一時停止を解除します。

twurl -H ads-api.x.com -X PUT "/9/accounts/xxxxxx/line_items/yyyy/?entity_status=ACTIVE"

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "grumpy cat",
    "placements": [],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "yyyy",
    "entity_status": "ACTIVE",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "ACTIVE",
      "account_id": "xxxxxx"
    }
  }
}

以上です。これで、タイムラインに配信されるプロモツイートキャンペーンが稼働し、ターゲティングと予算設定も完了しました。

​

目的ベースのキャンペーン

目的ベースのキャンペーンおよび課金モデルでは、広告主は自社のマーケティング目的に合致したアクションに対して支払うことができます。これを実現するには、ラインアイテムで適切な objective を設定してください。

ラインアイテムの書き込みエンドポイントで使用され、読み取りエンドポイントで返されるパラメータは objective です。このフィールドには、現時点では次の値を指定できます。

• APP_ENGAGEMENTS
• APP_INSTALLS
• FOLLOWERS
• ENGAGEMENTS
• REACH
• VIDEO_VIEWS
• PREROLL_VIEWS
• WEBSITE_CLICKS

目的によって、オークションにおけるキャンペーンの最適化方法と、そのキャンペーンの課金方法が変わります。APP_ENGAGEMENTS には CPAC、APP_INSTALLS には CPAC または CPI、WEBSITE_CLICKS には CPLC、FOLLOWERS には CPF、ENGAGEMENTS には CPE、REACH には CPM など、目的ごとに課金モデルを提供しています。

モバイルアプリプロモーションキャンペーンには、APP_ENGAGEMENTS か APP_INSTALLS のいずれかの objective を必ず含める必要があります。

注: 異なる objective を持つラインアイテムを同一キャンペーン内に含めることはできません。

Campaign objective	API objective	Media in Tweets	Pricing model
App re-engagements	APP_ENGAGEMENTS	画像または動画のアプリダウンロードカードが必須。	CPAC
App installs	APP_INSTALLS	画像または動画のアプリダウンロードカードが必須。	CPAC または CPI (charge_by を使用して設定)
Reach	REACH	制限なし。	CPM
Followers	FOLLOWERS	ツイートは必須ではありませんが推奨されます。フォロワーキャンペーン向けツイートのメディアに制限はありませんが、テキストのみのツイートを推奨します。 詳細情報	CPF
Engagements	ENGAGEMENTS	制限なし。	CPE
Video Views	VIDEO_VIEWS	動画会話カード、動画、または GIF が必須。	CPV または 3 秒間/100% 再生あたりのコスト
Pre-roll views	PREROLL_VIEWS	動画が必須。	CPV または 3 秒間/100% 再生あたりのコスト
Website Clicks	WEBSITE_CLICKS	ウェブサイトカードの使用を推奨しますが必須ではありません。ツイートには、ウェブサイトカードかウェブサイトリンクのいずれか一方 (両方ではない) を含める必要があります。	CPLC

​

資金源

資金源は、キャンペーンの予算を拠出する元となるものです。資金源は Ads API 経由で作成することはできず、利用可能にするには、与信枠の場合は X の広告主担当アカウントマネージャー、クレジットカードの場合は ads.x.com を通じて、あらかじめ設定されている必要があります。

アカウントに紐づくすべての funding_instruments の一覧を取得するには、GET accounts/:account_id/funding_instruments を参照してください。特定の資金源の詳細については、GET accounts/:account_id/funding_instruments/:funding_instrument_id を参照してください。

​

資金源の属性

説明: account_id、資金源の id、資金源の type、description、および io_header (インサーションオーダーのヘッダー ID) 。1 つの io_header が複数の資金源に関連付けられる場合がある点に注意してください。

資金提供の可否: able_to_fund と reasons_not_able_to_fund。

時間: created_at、updated_at、start_time、および end_time。いずれも文字列で表され、「%Y-%m-%dT%l:%M:%S%z」という形式でフォーマットされます。

ブール値のステータス: paused、deleted、および cancelled (true または false) 。

財務関連: currency (ISO-4217 形式) 、credit_limit_local_micro、credit_remaining_local_micro、および funded_amount_local_micro。通貨の値はマイクロ単位で表されます。USD の場合、$5.50 は 5.50*1e6、つまり 5,500,000 としてエンコードされます。元の金額 (通貨単位での値) を表現するには、すべての通貨について local micro に 1e6 (1_000_000) を掛ける必要があります。

​

属性の詳細

credit_limit_local_micro は CREDIT_CARD または CREDIT_LINE type のファンディングインスツルメントに対してのみ有効で、そのインスツルメントのクレジット上限額を表します。

funded_amount_local_micro は INSERTION_ORDER type のファンディングインスツルメントに対してのみ有効で、割り当てられた予算を表します。

credit_remaining_local_micro は CREDIT_LINE および AGENCY_CREDIT_LINE type のファンディングインスツルメントに対して有効です。これは、そのインスツルメントに対してすでに支出された金額を credit_limit_local_micro から差し引いた残りのクレジット額を表します。これは、funded_amount_local_micro と支出額との差額を表すものではありません。クレジット上限額と資金拠出額は、広告主との間で合意している基礎となる資金調達方法および支出契約が異なるため、区別しています。

​

資金手段の種類

クレジットカード

通常、アカウントマネージャーが付かないセルフサーブ広告主によって使用されます。

クレジットライン

インサーションオーダー (IO) の形式で提供され、アカウントマネージャーによって設定されます。

マルチハンドルクレジットライン

広告主は、この種類のクレジットラインを使って複数のハンドルにまたがるキャンペーンに資金を供給できます。この機能は、X のアカウントマネージャーが複数の @handle を特定のクレジットラインに関連付けて有効化することで利用できるようになります。

たとえば、@NikeSB と @NikeFuel はどちらも @Nike クレジットラインにアクセスできます。この資金手段も他のものと同様に利用可能です。funding_instrument エンドポイントに GET リクエストを送信することでデータを取得します。以下はレスポンスのサンプルです (CREDIT_LINE タイプに注目してください) 。

      GET https://ads-api.x.com/5/accounts/a0b1c3/funding_instruments

{
    "request": {
        "params": {
            "account_id": "a0b1c3"
        }
    },
    "data": [
        {
            "start_time": "2013-05-30T04:00:00Z",
            "description": "FakeNike - Credit Line",
            "credit_limit_local_micro": 150000000000,
            "end_time": null,
            "cancelled": false,
            "id": "i1234",
            "paused": false,
            "account_id": "a0b1c3",
            "reasons_not_able_to_fund": [],
            "io_header": null,
            "currency": "USD",
            "funded_amount_local_micro": 0,
            "created_at": "2013-05-30T18:16:38Z",
            "type": "CREDIT_LINE",
            "able_to_fund": true,
            "updated_at": "2013-05-30T18:16:38Z",
            "credit_remaining_local_micro": 123661919751,
            "deleted": false,
        }
    ],
    "data_type": "funding_instrument",
    "total_count": 1,
    "next_cursor": null
}

このFunding Instrumentについて特筆すべき点は、そのtypeであることと、それに関連付けられているすべてのアカウントで利用可能であるという事実だけです。もちろん、残りのクレジットは、このFunding Instrumentによって資金提供されている、これを共有するすべてのアカウントにまたがるキャンペーンすべての影響を受けます。特定のCredit Lineにどのアカウントが関連付けられているかの詳細は、API経由でも (ads.x.com経由でも) 取得できません。

Funding Instrumentの列挙値に関する詳細は、こちらをご参照ください。

​

ターゲティング

ターゲティングは Ads API の中核となる概念です。ターゲティングはラインアイテム単位で設定され、プレースメントごとに利用できるオプションが異なります。新しいターゲティング条件を設定するには POST accounts/:account_id/targeting_criteria を使用し、更新するには PUT accounts/:account_id/targeting_criteria を使用します。

すべてのラインアイテムの一覧を取得するには GET accounts/:account_id/line_items を使用し、特定のラインアイテムを取得するには GET  accounts/:account_id/line_items/:line_item_id を使用します。

​

配信面ごとのターゲティングオプション

Promoted Tweets と Promoted Accounts の広告プロダクトは、さまざまな配信面で利用可能です。Promoted Trends (PTr) は API 経由では利用できません。

利用可能な配信面の組み合わせについては、GET line_items/placements エンドポイントを参照してください。各配信面で利用できるターゲティングオプションは異なります。ロケーション、プラットフォーム、性別はすべての配信面で利用可能です。その他のオプションは、配信面の種類に応じて異なります。

• X Search: 年齢ターゲティング、デバイス、イベント、性別、キーワードタイプ (すべて) 、言語、ロケーション、ネットワークアクティベーション、通信事業者、プラットフォーム、プラットフォームバージョン、テイラードオーディエンス、WiFi のみ
• X Timeline: 年齢ターゲティング、デバイス、イベント、フォロワー (Followers Of) 、類似フォロワー (Similar to Followers Of) 、性別、興味・関心、言語、ロケーション、ネットワークアクティベーション、通信事業者、完全一致以外のキーワードタイプ、パートナーオーディエンスタイプ、プラットフォーム、プラットフォームバージョン、リターゲティングタイプ、テイラードオーディエンス、TV ターゲティングタイプ、WiFi のみ
• X Profiles & Tweet Details: 年齢ターゲティング、デバイス、イベント、フォロワー (Followers Of) 、類似フォロワー (Similar to Followers Of) 、性別、興味・関心、言語、ロケーション、ネットワークアクティベーション、通信事業者、完全一致以外のキーワードタイプ、パートナーオーディエンスタイプ、プラットフォーム、プラットフォームバージョン、リターゲティングタイプ、テイラードオーディエンス、TV ターゲティングタイプ、WiFi のみ

​

ターゲティング種別について

年齢ターゲティング: 特定の年齢バケットに基づいてユーザーをターゲットにします。年齢バケットの列挙値 (enum) の一覧は Enumerations ページにあります。

イベント: ターゲティングに使用するイベントを指定します。ターゲティングに使用できるイベントは (ラインアイテムごとに) 1 つのみです。GET targeting_criteria/events エンドポイントを使用して、ターゲティングに利用可能なイベントを取得します。

性別: 男性 (1) または女性 (2) をターゲットにします。すべてをターゲットにする場合は null のままにします。

Installed App Store Categories: インストール済み、または興味関心を示したアプリのカテゴリに基づいてユーザーをターゲットにする場合に、このターゲティングタイプを使用します。GET targeting_criteria/app_store_categories を参照してください。

インタレスト: ユーザーをインタレスト (関心) でターゲティングします。GET targeting_criteria/interests からインタレストのリストを取得します。最大 100 個までのインタレストをターゲティングできます。

Followers Of: 現在のアカウントにおける、完全にプロモート可能なユーザーのフォロワーをターゲットにします (注: 現時点では、そのアカウントのプライマリアカウントホルダーのみが、そのアカウントの完全にプロモート可能なユーザーです) 。GET accounts/:account_id/promotable_users を呼び出して、プロモート可能なユーザーの一覧を取得します。

Similar to Followers Of: 特定ユーザーのフォロワーと同じインタレストを持つユーザーをターゲットにします。最大 100 人までの Users を使用できます。

ロケーション: ターゲットにするロケーションを最大 2,000 件まで指定します。GET targeting_criteria/locations からリストを取得します。特定の国をターゲットにする広告には、追加の要件があります。詳細は Country Targeting and Display Requirements を参照してください。

キーワード: キーワードターゲティングのオプションは、掲載面の種別ごとに異なります。ターゲティングには (ラインアイテムごとに) 最大 1000 個のキーワードを使用できます。オプションについては「Keyword Types」セクションを参照してください。

Language Targeting: 特定の言語を理解しているユーザーをターゲットにします。

Mobile Network Operator Targeting: 広告主がモバイルキャリアに基づいてユーザーをターゲットにできるようにします。GET targeting_criteria/network_operators で取得できるターゲティング type NETWORK_OPERATOR を使用します。

New Mobile Device Targeting: ユーザーが自身のデバイスを通じて初めて X にアクセスした日付に基づいてユーザーにリーチします。ターゲティング type NETWORK_ACTIVATION_DURATION を使用し、LT を「より短い」、GTE を「以上」を表す operator_type として使用します。

Platforms、Platform Versions、Devices、および Wifi-Only: さまざまな軸でモバイルデバイスをターゲティングできるようにします。Platforms は、広いカテゴリの端末を対象にできる高レベルのターゲティング type です。例としては iOS や Android などがあります。Devices を使用すると、iPhone 5s、Nexus 4、Samsung Galaxy Note など、特定のモバイルデバイスのユーザーをターゲットにできます。Platform versions を使用すると、特定のモバイル OS のバージョン (ポイントリリースのレベルまで) を利用しているユーザーをターゲットにできます。例としては iOS 7.1 や Android 4.4 などがあります。Wifi-Only を使用すると、WiFi ネットワーク上でデバイスを使用しているユーザーのみをターゲットにできます。これを設定しない場合、キャリア回線と WiFi の両方を利用しているユーザーがターゲットになります。

• ユーザーは、重複がなければ platforms と devices をターゲティングできます。たとえば、platform として Blackberry、device として iPad Air を同時にターゲティングできます。
• ユーザーは devices と OS バージョンを同時にターゲティングできます。たとえば、iPad Air と iOS >= 7.0 をターゲティングできます。
• ユーザーは devices より広い platforms をターゲティングすることはできません。たとえば、iOS と iPad Air を同時にターゲティングすることはできません。

[Tailored Audiences]/x-ads-api/audiences: 承認済みの広告パートナーを通じてユーザーにリーチし、顧客グループをターゲティングしてX上でつながることができます。

TV Targeting

TV Show Targeting: 特定のテレビ番組に反応している人々にリーチします。このターゲティング条件は、キャンペーンがアクティブな間、TV_SHOW ターゲティングタイプを使用して継続的にターゲティングするように設定できます。利用可能なテレビ番組を確認するには、GET targeting_criteria/tv_markets エンドポイントおよび GET targeting_criteria/tv_shows エンドポイントを使用します。

Tweet Engager Retargeting

Tweet engager リターゲティングを使用すると、広告主は、これまでに自社のプロモーションまたはオーガニックのツイートに対してX上で表示またはエンゲージしたユーザーを、デバイスをまたいでターゲティングできます。このターゲティングにより、広告主は、自社のコンテンツをX上で閲覧またはエンゲージした人々の中から、その後のメッセージやオファーに対してさらにエンゲージしたりコンバージョンする可能性が高いユーザーをフォローアップできます。ユーザーは、表示またはエンゲージから数分以内にターゲット対象となり、エンゲージメントについてはその後最大90日間、表示については30日間対象となります。

Tweet Engager ターゲティングタイプ:

• ENGAGEMENT_TYPE: ターゲティング値として IMPRESSION または ENGAGEMENT のいずれかを受け取ります。これは、表示されたユーザー (IMPRESSION) をターゲティングするか、エンゲージしたユーザー (ENGAGEMENT) をターゲティングするかを指定します。
• CAMPAIGN_ENGAGEMENT: ターゲティング値としてキャンペーンの ID を使用します。このキャンペーンに対してエンゲージした、または表示されたユーザー (ENGAGEMENT_TYPE に応じて) がターゲットとなります。
• USER_ENGAGEMENT: ターゲティング値としてプロモーション対象ユーザーの ID を使用し、広告主のオーガニックコンテンツに表示またはエンゲージしたユーザー (ENGAGEMENT_TYPE に応じて) をターゲティングします。これは、その広告アカウントに紐づくプロモーション対象ユーザーの ID である必要があります。

注: ENGAGEMENT_TYPE は、少なくとも1つの有効な CAMPAIGN_ENGAGEMENT または USER_ENGAGEMENT の値と合わせて指定する必要があります。両方の Tweet engager ターゲティングタイプを同時に指定することもでき、1つのラインアイテムで複数のキャンペーンをターゲティングできます。

Video Viewer Targeting: Video viewer ターゲティングは Tweet engager ターゲティングを拡張したもので、これまでにX上の動画を一部または全部視聴したオーディエンスを広告主がターゲティングできるようにします。広告主は、オーガニック動画、プロモーション動画、またはその両方をターゲティングできます。プロモーション動画は、動画再生数を目的としたキャンペーンやラインアイテムに限定されません。

Video Viewer ターゲティングタイプ:

• VIDEO_VIEW: 動画を再生するためにクリックした、または自動再生で3秒間視聴したユーザー
• VIDEO_VIEW_PARTIAL: 動画の50%を視聴したユーザー
• VIDEO_VIEW_COMPLETE: 動画の少なくとも95%を視聴したユーザー

Tweet engager ターゲティングと同様に、ENGAGEMENT_TYPE を使用する場合、ラインアイテムのターゲティング条件には次のいずれか、または両方が含まれている必要があります。

• CAMPAIGN_ENGAGEMENT: ターゲティング値としてキャンペーンの ID を使用します。このキャンペーン内で動画を視聴したユーザー (ENGAGEMENT_TYPE に基づく) がターゲットとなります。
• USER_ENGAGEMENT: ターゲティング値としてプロモーション対象ユーザーの ID を使用し、広告主のオーガニックコンテンツ内の動画を視聴したユーザー (ENGAGEMENT_TYPE に基づく) をターゲティングします。これは、その広告アカウントに紐づくプロモーション対象ユーザーの ID である必要があります。

Keyword Types

概念的な概要については、キーワードターゲティング に関するサポート文書を参照してください。

• Broad (デフォルト値) : 単語の順序に関係なく、すべての単語にマッチします。大文字小文字、複数形、時制には依存しません。可能な場合、自動的に拡張されます (例: “car repair” は “automobile fix” にもマッチします) 。拡張なしでターゲティングしたい場合は、「+boat +jet」のように、キーワードの前に + 記号を追加する必要があります。+ を付けずにキーワードを使用すると、Broad Match がデフォルトとして適用されます。
• Unordered (非推奨) : 単語の順序に関係なく、すべての単語にマッチします。大文字小文字、複数形、時制には依存しません。
• Phrase: キーワード文字列と同じ語句を含むフレーズにマッチし、他のキーワードが含まれていてもかまいません。
• Exact: キーワード文字列と完全に一致する場合のみにマッチし、それ以外にはマッチしません。
• Negative: クエリ内のどこかに、これらすべてのキーワードが含まれる検索にマッチしないようにします。順序には関係なく、他の単語が含まれていても除外されます。
• Negative Phrase: クエリ内のどこかに、このキーワード文字列と同じ語句が含まれる検索にマッチしないようにします。他の単語が含まれていても除外されます。
• Negative Exact: これらのキーワードと完全に一致し、他の単語を一切含まない検索にマッチしないようにします。  

Emoji targeting

絵文字ターゲティングはキーワードターゲティングを通じて利用できます。絵文字ターゲティングを利用するには、その絵文字を表す Unicode コードポイント (たとえば「喜びの涙を浮かべた顔」絵文字 (😂) であれば、U+1F602 (UTF-8 では xF0x9Fx98x82) ) を使ったキーワードターゲティングを作成します。利用可能な絵文字は、twemoji のリストで確認できます。特定の絵文字をターゲティングすると、そのすべてのバリエーションが対象になります。

必須／任意などの別や各値の詳細の概要については、PUT accounts/:account_id/targeting_criteria を参照してください。

​

ターゲティング条件の組み合わせ

新しいキャンペーンワークフロー

地域、性別、言語、デバイス／プラットフォームなどの条件で、広範なターゲティングを行うキャンペーンを作成できます。広告主は、その広範なターゲティングに加えて、さらに詳細なターゲティング条件 (例: 興味関心、キーワード、フォロワー、テイラードオーディエンス、TV) を組み合わせることができます。ラインアイテムにターゲティング条件が 1 つも指定されていない場合、そのラインアイテムは全世界のすべてのユーザーを対象とします。

「プライマリ」タイプ	その他のタイプ
フォロワー	位置情報
テイラードオーディエンス	性別
興味関心	言語
キーワード	デバイスとプラットフォーム
TV	年齢

ターゲティング条件は、広告グループに対して次のように組み合わされます。

• 「プライマリ」ターゲティングタイプは ∪ (論理和) で結合されます。
• その他のターゲティングタイプは AND で結合されます。
• 同じタイプ同士は OR で結合されます。

いくつかの例

概要: [(フォロワー) ∪ (テイラードオーディエンス) ∪ (興味関心) ∪ (キーワード)] AND (位置情報) AND (性別) AND (言語) AND (デバイスとプラットフォーム)

地域の例:

あるキャンペーンの広告グループで、次のようなターゲティングを行いたいとします。

• 米国、イングランド、カナダにいる X ユーザー (位置情報)
• かつ女性 (性別)
• テイラードオーディエンスリストに基づく (「プライマリ」)
• かつキーワードによる指定 (「プライマリ」)

この場合のターゲティング条件は次のようになります。

[US OR GB OR CA] AND [Female] AND [Tailored Audiences ∪ Keyword]

​

追加の例

• 性別と地域を選択し、プライマリターゲティングは設定しない場合: (Male) AND (US OR GB)
• 性別、地域、インタレストを選択する場合: (Female) AND (CA) AND (Computers OR Technology OR Startups)
• 性別、地域、インタレスト、テイラードオーディエンス、キーワードを選択する場合: (Male) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)

​

予算ペーシング

広告主は、プロモツイートおよびプロモアカウントキャンペーンにおいて、1 日あたりの予算がどの程度のペースで消化されるかを、これまで以上に細かく制御できるようになりました。デフォルトで有効になっている標準配信を利用すると、1 日を通して均等なペースで予算が消化されます。

標準配信をオフにすると、日別予算を使い切るまで、インプレッションの配信およびエンゲージメントの獲得を可能な限り速く行います。ターゲティングや競合状況によっては、これは 1 日のかなり早い時間帯に発生する場合があります。これを高速配信 (accelerated delivery) と呼びます。

はじめに

標準配信はすべてのキャンペーンでデフォルトのオプションであるため、オフにしない限り操作は不要です。キャンペーンで日別予算をできるだけ早く使い切るようにするには、standard_delivery パラメータを false に設定し、配信ペースを高速配信に変更します (GET accounts/:account_id/campaigns を参照) 。

注意事項

• 「1 日」は、X の広告主アカウントのタイムゾーン (例: America/Los_Angeles) に基づきます。
• 初期の結果からは、標準配信により 1 日を通してより一貫した配信が行われることで、広告主にとっての eCPE/CPF が改善されることが示唆されています。

予算とペーシングの詳細については、Bidding and Auctions FAQ を参照してください。

​

ターゲット別入札

キャンペーン管理

​

入札戦略

キャンペーン作成ワークフローを簡素化し、複数パラメータの組み合わせに関する混乱を軽減するために、入札戦略 (Bid Strategy) という概念を導入しました。

以前の (レガシーとしてマークされている) パラメータの組み合わせはすべて、同等の goal パラメータを設定することで実現できます。さらに詳しい情報は、こちらのアナウンスをご覧ください。

例：

キャンペーン目的	レガシー	Ads API v10+
App Installs	bid_type= AUTO bid_unit = APP_INSTALLS charge_by = APP_CLICKS	goal = APP_INSTALLS bid_strategy = AUTO
Website Clicks	bid_type = TARGET (注: 一部のキャンペーン目的では bid_unit は不要でした)	bid_strategy = TARGET

​

ターゲット入札

ターゲット入札を使用すると、支払いたい目標コストを指定でき、X Ads プラットフォームがその目標コスト付近またはそれ以下に収まるようにしつつ、パフォーマンス最大化のためにキャンペーンを最適化します。

この機能により、コストを管理しつつ、リンクのクリック、リード獲得、フォローなど、望ましいアクションを起こす可能性が特に高いユーザーにリーチする柔軟性が得られます。これは、キャンペーン設定および最適化 (入札オプションを含む) において、より多くの選択肢を求める広告主にとって非常に強力な機能です。

対応するキャンペーン目標を持つラインアイテム向けに、支払いたい目標コストを指定できる、新しい入札額の価格設定メカニズムを導入しました。広告プラットフォームは、指定した目標の 20% 以内に平均コストを抑えるよう努めながら、より多くの成果を得られるよう、お客様に代わって動的に入札します。ラインアイテムの bid_strategy 設定に TARGET の値を設定することで、次のような関連するキャンペーン目標でターゲット入札を有効にできます。

• WEBSITE_CLICKS
• WEBSITE_CONVERSIONS 
• APP_INSTALLS 
• APP_ENGAGEMENTS
• REACH

​

国別ターゲティングおよび表示要件

キャンペーン管理

国別のターゲティングおよび表示要件はこのページに掲載されています。これらの要件は、すべてのパートナーが遵守しなければなりません。

​

Russia

X の広告ポリシー では、ロシアをターゲットとする広告について、ロシア語以外の言語での配信を禁止しています。あなたのユーザーがロシアを明示的にターゲットとして指定する場合、次の警告メッセージをユーザーに表示する必要があります。

ロシアを対象とする広告はロシア語でなければなりません。

​

パートナー管理のファンディングインストゥルメント

オンボーディングフローでは、X アカウント用の ads.x.com アカウントを設定します。このアカウントはパートナーが Ads API を通じて管理でき、広告出稿にかかる費用はパートナーに請求されます。  

​

パートナーの初期セットアップ

新しい PMFI Ads API パートナーの初期セットアップには、必要な情報のやり取り完了から最長で 3 週間かかります。プロセスを開始するには、以下の情報を、X の技術担当窓口およびパートナーとの連携を管理している X 担当者の両方と共有する必要があります。

• パートナーは自社の PGP/GPG 公開鍵を共有する必要があります。 Ads API パートナーと X 間で共有シークレットキーを交換する必要があります。これはオンボーディングフロー中のデータ検証に使用されます。
• Ads API アクセスに使用する X app の app_id または consumer_secret 。 developer.x.com 上で X アカウントにログインしている場合、app dashboard から既存の X app を表示および編集できます。新しく X app を作成する必要がある場合は、承認済みの開発者アカウントが必要です。X では、本番＋サンドボックス用に 1 つの app と、任意でサンドボックス専用アクセス用に 1 つの app が許可されています。X app は、パートナーが管理する企業アカウントの X ハンドル上で作成する必要があります。  

​

広告主オンボーディングフロー

広告主のオンボーディングフローは、Web ブラウザを介して次のように行われます。

1. ユーザーはパートナーの Web サイト上でオンボーディングフローを開始し、オンボードしたいハンドル (@ユーザー名) を入力します。
2. パートナーは署名付きペイロードを含めたうえで、ユーザーを ads.x.com 上の URL にリダイレクトします。このペイロードには、パートナーの API app_id、オンボード対象となる X ハンドルの X user_id、コールバック URL、および以下で説明するその他のフィールドが含まれます。
3. ユーザーは標準の x.com のログインページを使用して ads.x.com にサインインするよう求められます。
4. ユーザーがログインすると、オンボーディングプロセスが開始されます。このステップには、広告審査、アカウントの確認、その他のチェックが含まれます。
5. すべてのオンボーディング作業が完了すると、ユーザーは Ads API パートナーによって指定されたコールバック URL に、成功または失敗を示すペイロードとともにリダイレクトされます。このフローには 3-legged 認可プロセスも含まれます。  

​

オンボーディングリダイレクトペイロード

リダイレクト用 URL:

https://ads.x.com/link_managed_account

リダイレクト URL には、次のパラメータが付与されます:

Name	Type	Description
callback_url	URL エンコードされた文字列	アカウントリンクの処理が結果にかかわらず完了した後、この URL にユーザーがリダイレクトされます。プロトコルの詳細については、パートナーリダイレクト URL セクションを参照してください
client_app_id	integer	管理パートナーを識別するために使用される X API のクライアント App の id
promotable_user_id	integer	プロモーションを管理パートナーが運用する対象となる @handle の X の user_id。ads.x.com にログインしてリンク処理を完了するユーザーと同一であることを確認するために使用されます
fi_description	URL エンコードされた文字列 (最大 255 文字)	資金提供手段名。この名前は、資金提供手段を取得した際に API の description フィールドに表示されます。funding_instrument の description が指定された場合、既存の funding_instrument は一時停止され、新しいマネージドパートナー用の資金提供手段が設定されます (同じ名前のものがすでに存在する場合は何も起こりません)。
timezone	Area/Location 形式の文字列	日次予算が適用される日付を決定し、請求額が集計されるタイムゾーンとして使用されます
currency	ISO 4217 通貨コード	入札額の入力および請求額の請求に使用される通貨
country	ISO 3166-1 alpha 2 国コード	アカウントの請求先の国
signature	下記の説明のとおり、URL エンコードおよび base64 エンコードされたバイナリデータ	共有シークレットと他のパラメータを組み合わせて、呼び出しの真正性およびパラメータの有効性を検証するための署名。

​

コールバック URL ペイロード

ベースとなるリダイレクト URL は、アカウントリンクリクエストの callback_url パラメータで指定されます (上記参照) 。ads.x.com によって追加されるパラメータは次のとおりです。

Name	Type	Description
status	string	OK アカウントが作成されたか、既存の利用可能なアカウントが見つかった場合。 ACCOUNT_INELIGIBLE パートナー固有の制約が満たされていない場合 USER_MISMATCH ads.x.com へのサインインに使用された X アカウントが、アカウントリンクリクエストの promotable_user_id と異なる場合 INCOMPLETE_SERVING_BILLING_INFO タイムゾーン、通貨、または国が指定されていない場合 INVALID_COUNTRY 無効な国の値が指定された場合 INVALID_CURRENCY 無効な通貨の値が指定された場合 INVALID_TIMEZONE 無効なタイムゾーンの値が指定された場合
account_id	URL encoded string	リンクされたアカウントの X 広告アカウント id
funding_instrument_id	URL encoded string	アクティブなパートナー管理ファンディングインストゥルメントの ID
signature	URL encoded, base64 encoded binary code, as explained below	共有シークレットと他のパラメータを組み合わせて呼び出しの正当性およびパラメータの有効性を検証する、Base64 でエンコードされた HMAC-SHA1 署名。コールバック URL が、そのアカウントリンクプロセスの対象となった X の user_id に対してのみ有効となるようにするため、リクエストに署名する際には共有シークレットに X の user_id を (& を用いて) 連結する必要があります。

コールバック URL が、そのアカウントリンクプロセスの対象となった X の user_id に対してのみ有効となるようにするため、リクエストに署名する際には、共有シークレットに X の user_id を (& を用いて) 連結する必要があります。  

​

リクエストおよびコールバック URL への署名

/link_managed_account へのリクエストおよびコールバック URL が有効なものであることを保証するために、リクエストは送信元で署名され、受信側で検証が行われてから受信側が処理を実行する必要があります。X と管理パートナーの間で共有されているシークレットを用いてリクエストに署名することで、双方は認可された相手から送信されたリクエストのみを受け入れることができます。

署名生成アルゴリズムは OAuth で使用されているものとほぼ同じです。

次のように署名用ベース文字列を作成します:

• HTTP メソッドを大文字に変換し、その値をベース文字列とします。
• ベース文字列の末尾に ‘&’ 文字を追加します。
• URL (パラメータなし) をパーセントエンコードし、ベース文字列に追加します。
• ベース文字列の末尾に ‘&’ 文字を追加します。
• 次の手順で構築される、パーセントエンコード済みのクエリ文字列を追加します:
• 署名対象となるすべてのキーと値をパーセントエンコードします。
• パラメータの一覧をキーでアルファベット順にソートします。
• 各キー/値のペアについて (パートナーのリダイレクト URL 用の primary_promotable_user_id を含む) :
• パーセントエンコード済みのキーをクエリ文字列に追加します。
• ‘=’ 文字をベース文字列に追加します。
• パーセントエンコード済みの値をクエリ文字列に追加します。
• パーセントエンコードされた key=value のペア同士を ‘&’ 文字で区切ります。
• 事前に共有されているシークレットをキー、ベース文字列を値として HMAC-SHA1 アルゴリズムを用い、署名を生成します。
• ステップ 2 の出力を Base64 エンコードし、末尾の改行文字を削除してから、ステップ 3 で生成した署名をパーセントエンコードし、それを signature パラメータとして URL に追加します。  

​

署名の例

リンクアカウントリクエストへの署名

GET リクエストであると仮定した場合に署名する URL:

https://ads.x.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1

この URL には次のパラメータがあります:

callback_url = https://managingpartner.com/link_account_callback\ client_app_id = 12345
fi_description = some name
promotable_user_id = 1

HTTP メソッドとパラメータを除いた URL から成るベース文字列は、手順 a ～ d に従うと次のようになります:

GET https://ads.x.com/link_managed_account

手順 e のサブステップによって生成されるクエリ文字列は次のとおりです:

callback_url=https://managingpartner.com/link_account_callback&client_app_id=12345&fi_description=some name&promotable_user_id=1

キーと値のペアはキー名でソートされている点に注意してください。

パーセントエンコードされたクエリ文字列は次のとおりです:

callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

手順 a ～ d と e を結合した完全なベース文字列は次のようになります:

GET https://ads.x.com/link_managed_account&callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

hmac-sha1 アルゴリズムを使用して、これに「secret」という単語をキーとして署名します。結果は Base64 エンコードされ、末尾の「\n」を取り除いた形で表されます (手順 2 および 3): KBxQMMSpKRrtg9aw3qxK4fTXvUc=

この署名は、その後 (パーセントエンコードしたうえで) 元の URL の末尾に signature パラメータとして追加されます (手順 4):

https://ads.x.com/link_managed_account?callback_url=https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&client_app_id=12345&fi_description=some%20name&promotable_user_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D

パートナーリダイレクト URL (アカウントリンクリクエストのコールバック) への署名
GET リクエストであると仮定した場合に署名する URL:

https://managingpartner.com/link_account_callback?status=OK&account_id=ABC&funding_instrument_id=DEF

この URL には次のパラメータがあります:

account_id = ABC、funding_instrument_id = DEF、status = OK

HTTP メソッドとパラメータを除いた URL から成るベース文字列は、手順 a ～ d に従うと次のようになります:

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&“

手順 e のサブステップによって生成されるクエリ文字列は次のとおりです:

account_id=ABC&funding_instrument_id=DEF&status=OK

パーセントエンコードされたクエリ文字列は次のとおりです:

account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

手順 a ～ d と e を結合した完全なベース文字列は次のようになります:

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

hmac-sha1 アルゴリズムを使用して、これに「secret」という単語と、元のリンクリクエストが行われた対象の X ユーザー id である 1 (promotable_user_id = 1、上記参照) を組み合わせた「secret&1」をキーとして署名します。

結果は Base64 エンコードされ、末尾の「\n」を取り除いた形で表されます (手順 2 および 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=

このシグネチャは、その後、元の URL の末尾に signature パラメータ (ステップ 4) として、パーセントエンコードされた状態で追加されます:

https://managingpartner.com/link_account_callback?&status=OK&account_id=ABC&funding_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D

​

共有キーの使用／更新

署名アルゴリズムは、複数のキーに対して繰り返し利用できる必要があります。これにより、複数の共有キーを併用でき、共有キーを定期的にローテーションすることが可能になります。  

​

partner_managed_funding_instrument の作成

fi_description パラメータが指定されており、アカウント内に同じ名前の既存の partner_managed_funding_instrument が存在しない場合、新しい partner_managed_funding_instrument が作成され、既存のすべての partner_managed_funding_instrument は一時停止されます。

同じ名前の partner_managed_funding_instrument が存在する場合、新しいものは作成されません。  

​

オンボーディングフローの再実行 / トークンのリフレッシュ

API の access token が失われた場合、オンボーディングフローを再度実行できます。オンボーディングフローの実装では、ユーザーがログインしている必要があります。ユーザーが promotable_user_id と一致し、関連付けられた広告アカウントが見つかり、その他の条件にも問題がなければ、ユーザーは callback URL にリダイレクトされ、パートナーは OAuth フローを開始して access token を取得できます。  

​

リダイレクトされないエラーフロー

account link の URL が無効なパラメーター付きで呼び出された場合、OAuth フローで無効または期限切れのパラメーターが指定されたときに表示されるページと同様のページがユーザーに表示されます。  

​

PMFI の継続的な更新

広告主のオンボーディングが完了すると、その資金手段は、それを管理するパートナーのみが PUT accounts/:account_id/funding_instruments/:funding_instrument_id エンドポイントを使用して管理できます。

​

プレースメント

X 広告が表示される場所はいくつかあります。これは、ラインアイテムの placements パラメータで設定します。指定可能な値は次のとおりです。

• ALL_ON_TWITTER
• PUBLISHER_NETWORK
• TWITTER_PROFILE
• TWITTER_SEARCH
• TWITTER_TIMELINE
• SPOTLIGHT
• TREND

ラインアイテムの product_type と objective によって、利用可能なプレースメントが決まります。GET line_items/placements エンドポイントを使用して、各 product_type ごとの有効なプレースメントオプションを取得できます。

さらに、以下の表は有効なプレースメントと objective の組み合わせを示しています。

Objective	ALL_ON_TWITTER	TWITTER_PROFILE	TWITTER_SEARCH	TWITTER_TIMELINE
APP_ENGAGEMENTS	✔	✔	✔	✔
APP_INSTALLS	✔	✔	✔	✔
REACH	✔	✔	✔	✔
FOLLOWERS	✔	✔	✔	✔
ENGAGEMENTS	✔	✔	✔	✔
VIDEO_VIEWS	✔	✔	✔	✔
PREROLL_VIEWS	✔	✔	✔	✔
WEBSITE_CLICKS	✔	✔	✔	✔

注: プレースメントとして TWITTER_PROFILE だけを指定することはできません。

注: TWITTER_SEARCH にはキーワードターゲティングが必要です。

注: REACH objective には TWITTER_TIMELINE プレースメントを必ず含める必要があります。ALL_ON_TWITTER、TWITTER_TIMELINE を含む任意のプレースメントの組み合わせ、または TWITTER_TIMELINE 単独を指定できます。

​

広告グループに関するよくある質問

このドキュメントでは、X の Ads API における広告グループに関して、よく寄せられる質問をまとめています。

​

広告グループとは何ですか？

広告グループは、Ads API では line item と呼ばれ、キャンペーンの配下に属し、特定の X ユーザーの集合に対するターゲティングおよび入札に使用されます。広告主は、ツイートやメディア (例：インストリーム広告として配信される動画など) を line item に関連付けることでプロモーションを行います。

​

Ad Group をどのように作成しますか？

Ad Group は、同じキャンペーン ID に対して POST accounts/:account_id/line_items を複数回呼び出し、その各 line item に (まったく異なる内容でもよい) ターゲティングとツイートを関連付けることで作成します。1 つのキャンペーン当たりの line item の上限は 100 個で、1 つの広告アカウント当たりの有効なキャンペーンの上限は 200 個です。すべてのキャンペーンを通じて、1 つの広告アカウント当たり有効な line item は最大 8,000 個までです。

​

なぜ Ad Groups をサポートする必要があるのですか？

Ad Groups は、広告主がキャンペーンを整理・最適化・管理しやすくすることを目的としています。

Ad Groups の利点は、入札単価、予算、クリエイティブ、ターゲティングにまたがるさまざまな戦略を比較・コントロールできる点にあります。複数の Promoted Tweets を 1 つの line item に関連付けると、オークションはまずそのグループ内から最適なツイートを選択し、そのうえで、すべての line item の中からそのキャンペーンにとって最適なツイートを選択します。単一のツイートのみを含む Ad Groups を複数持っている場合は、実質的には、その Ad Group ごとにパフォーマンスが高くなりそうなツイートが選択されることになります。

Ad Groups を使用すると、広告主はターゲティングと入札単価を、従来よりはるかに多くの組み合わせパターンに分割でき、一般的にターゲティングを論理的なグループに分けて管理できるようになります。

特に Ads API ツールは、Ad Groups を用いたきめ細かい最適化ルールを中心に構築できるため、line item とクリエイティブの組み合わせが大規模になることから手動編集では困難な最適化も実現しやすくなります。

​

Ad Groups キャンペーンにおいて、ラインアイテムの予算はキャンペーン予算とどのような関係がありますか？

ラインアイテムに設定する total_budget_amount_local_micro は、親キャンペーンの総予算を超えることはできません。同様に、ラインアイテムの bid_amount_local_micro の値は、親キャンペーンの daily_budget_amount_local_micro または total_budget_amount_local_micro を超えないようにする必要があります。これらの値を誤って設定すると、キャンペーン全体が一時停止状態となり、配信不可の状態になる可能性があります。

なお、キャンペーン全体の総予算は、その子である各ラインアイテムの予算合計よりも少なく設定することができます。また、ラインアイテム間の予算配分は一部 Ads API ツール側に委ねられており、ターゲティング (ラインアイテム) の日々のパフォーマンスは、X のリアルタイム性により日ごとに大きく変動し得るため、それに応じて効果的に最適化・調整されます。

​

広告グループは単一のラインアイテムよりも良い成果を上げられますか？

キャンペーンの成果は多くの要因に左右されますが、最終的にはツイートが成果を決定づける要素となります。ラインアイテムは、ツイートがユーザーへの配信対象として選考に残るかどうかを左右する要素として扱われます。

同じユーザー層をターゲティングしているラインアイテムは、ユーザーが重複していると見なされます。ラインアイテム間のこのターゲティングの重複を減らすことがベストプラクティスとされており、そうすることで、最も高い成果を上げるユーザー層を明確に特定できるようになります。

​

ガイド

​

Video Views プレロール目的

このガイドでは、Ads API で PREROLL_VIEWS キャンペーンを設定するために必要な手順の概要を説明します。大まかに言えば、これらのキャンペーンは「Curated Categories」と「Content Categories」の 2 種類に分類され、後者は Ads UI 上では「Standard Categories」と呼ばれます。  

​

必要なエンドポイント

• Chunked media upload (動画をアップロードするため)
• POST accounts/:account_id/media_library (動画を広告アカウントに関連付ける)
• POST accounts/:account_id/campaigns (キャンペーンを作成)
• GET content_categories (コンテンツカテゴリと IAB カテゴリの対応関係を取得)
• GET accounts/:account_id/curated_categories
• GET publishers
• POST accounts/:account_id/line_item_curated_categories
• POST accounts/:account_id/line_items (広告グループを作成)
• POST accounts/:account_id/media_creatives (広告グループに動画を関連付ける)
• POST accounts/:account_id/preroll_call_to_action (CTA とリダイレクト URL を設定)
• POST batch/accounts/:account_id/targeting_criteria (ターゲティング)

​

手順

​

動画をアップロードする

動画のアップロードは次の2つの手順で行います。

​

動画メディアをアップロードする

まず、Chunked media upload エンドポイントを使用して、処理のために動画を X にアップロードします。このエンドポイントで最初に INIT を呼び出す際には、media_category=amplify_video を指定する必要があります。動画はチャンクに分割してアップロードします。STATUS が返す state が succeeded になったら、次の手順に進むことができます。チャンクアップロードエンドポイントを使用したメディアアップロードの詳細については、Promoted Video Overview を参照してください。

​

動画を広告アカウントに追加する

STATUS コマンドで返される状態が succeeded になったら、そのエンドポイントから返された media_key を使用し、POST accounts/:account_id/media_library エンドポイントを呼び出して、動画を広告主のメディアライブラリに追加します。

POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_931236738554519552

{
 "request": {
   "params": {
     "account_id": "55w3kv",
     "media\_key": "3\_931236738554519552"
   }
 },
 "data": {
   "tweeted": false,
   "name": null,
   "file_name": null,
   "media\_url": "https://video.twimg.com/amplify\_video/1059840836186165250/vid/568x320/Gr2l1fB1X7xotKwC.mp4?tag=8",
   "media\_category": "AMPLIFY\_VIDEO",
   "media\_key": "3\_931236738554519552",
   "created_at": "2017-11-16T19:05:14Z",
   "media\_status": "TRANSCODE\_COMPLETED",
   "media_id": 931236738554519552,
   "media_type": "VIDEO",
   "updated_at": "2017-11-16T19:05:23Z",
   "deleted": false
 }
}

​

キャンペーンの設定

​

キャンペーンの作成

キャンペーンと広告グループ (line item/ad group) を作成します。line item (ラインアイテム) は objective を VIDEO_VIEWS_PREROLL、product_type を MEDIA に設定して作成します。categories パラメータには、適切な広告主の業種カテゴリを設定します。

POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding\_instrument\_id=103hp9&start\_time=2021-02-10&entity\_status=PAUSED&daily\_budget\_amount\_local\_micro=55000000

{
  "request": {
    "params": {
      "name": "test-curated-categories-api",
      "start_time": "2021-02-10T00:00:00Z",
      "daily\_budget\_amount\_local\_micro": 55000000,
      "funding\_instrument\_id": "103hp9",
      "entity_status": "PAUSED",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
      "EXPIRED",
      "PAUSED\_BY\_ADVERTISER",
      "FUNDING_PROBLEM"
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "PAUSED",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

​

ラインアイテムの作成

ラインアイテムでは、GET content_categories エンドポイントから取得した適切な IAB カテゴリのセットを、categories パラメータに設定する必要があります。これらのコンテンツカテゴリは、それぞれ 1 つ以上の IAB カテゴリに対応しています。

これらの値を使用するには、パートナーは適切なコンテンツカテゴリを選択し、レスポンスで返される iab_categories のセット全体を使用して、ラインアイテムエンドポイントの categories パラメータを設定する必要があります。iab_categories のうち一部だけを適用した場合でも、そのグループ全体が当該ラインアイテムに設定されます。例えば、

GET https://ads-api.x.com/8/advertiser\_business\_categories

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": \[
    {
      "id": "1jl",
      "name": "消費財",
      "iab_categories": \[
        "IAB9-26",
        "IAB9-18",
        "IAB9-29",
        "IAB9-1",
        "IAB9-8",
        "IAB9-22",
        "IAB6",
        "IAB9-5",
        "IAB9-12",
        "IAB9-11",
        "IAB9-23",
        "IAB9-14",
        "IAB4",
        "IAB9-25",
        "IAB9-17",
        "IAB23",
        "IAB9-24",
        "IAB9-13",
        "IAB16",
        "IAB9-4",
        "IAB9-9",
        "IAB9-20",
        "IAB22",
        "IAB9-28",
        "IAB9-27",
        "IAB9-16",
        "IAB9-31",
        "IAB9-3",
        "IAB9-19",
        "IAB10",
        "IAB9-2",
        "IAB9-6",
        "IAB9-21",
        "IAB9-10",
        "IAB9-15"
      \]
    },
    {
      "id": "1jm",
      "name": "ヘルスケア・医薬品",
      "iab_categories": \[
        "IAB7"
      \]
    },
    {
      "id": "1jn",
      "name": "アルコール",
      "iab_categories": \[
        "IAB8-5",
        "IAB8-18"
      \]
    },
    {
      "id": "1jo",
      "name": "飲食",
      "iab_categories": \[
        "IAB8-10",
        "IAB8-8",
        "IAB8-7",
        "IAB8-15",
        "IAB8-3",
        "IAB8-4",
        "IAB8-1",
        "IAB8-16",
        "IAB8-12",
        "IAB8-13",
        "IAB8-17",
        "IAB8-11",
        "IAB8-6",
        "IAB8-9",
        "IAB8-2",
        "IAB8-14"
      \]
    },
    {
      "id": "1jp",
      "name": "金融サービス",
      "iab_categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \]
    },
    {
      "id": "1jq",
      "name": "小売",
      "iab_categories": \[
        "IAB18"
      \]
    },
    {
      "id": "1jr",
      "name": "旅行",
      "iab_categories": \[
        "IAB20"
      \]
    },
    {
      "id": "1js",
      "name": "ゲーム",
      "iab_categories": \[
        "IAB9-30"
      \]
    },
    {
      "id": "1jt",
      "name": "テクノロジー",
      "iab_categories": \[
        "IAB19-22",
        "IAB19-13",
        "IAB19-4",
        "IAB19-33",
        "IAB19-26",
        "IAB19-3",
        "IAB19-16",
        "IAB19-9",
        "IAB19-32",
        "IAB19-25",
        "IAB19-30",
        "IAB19-36",
        "IAB19-21",
        "IAB5",
        "IAB19-12",
        "IAB19-28",
        "IAB19-17",
        "IAB19-8",
        "IAB19-7",
        "IAB19-24",
        "IAB15",
        "IAB19-11",
        "IAB19-31",
        "IAB19-20",
        "IAB19-15",
        "IAB19-1",
        "IAB19-35",
        "IAB19-29",
        "IAB19-34",
        "IAB19-23",
        "IAB19-2",
        "IAB19-5",
        "IAB19-14",
        "IAB19-27",
        "IAB19-10",
        "IAB19-19"
      \]
    },
    {
      "id": "1ju",
      "name": "通信",
      "iab_categories": \[
        "IAB19-6",
        "IAB19-18"
      \]
    },
    {
      "id": "1jv",
      "name": "自動車",
      "iab_categories": \[
        "IAB2"
      \]
    },
    {
      "id": "1jw",
      "name": "メディア・エンターテインメント",
      "iab_categories": \[
        "IAB14-8",
        "IAB14-4",
        "IAB1-5",
        "IAB14-7",
        "IAB1-7",
        "IAB17",
        "IAB14-3",
        "IAB1-1",
        "IAB12",
        "IAB1-6",
        "IAB25-1",
        "IAB1-2",
        "IAB14-2",
        "IAB14-6",
        "IAB1-3",
        "IAB1-4",
        "IAB14-5"
      \]
    },
    {
      "id": "1jx",
      "name": "政治",
      "iab_categories": \[
        "IAB11-4"
      \]
    },
    {
      "id": "1jy",
      "name": "ギャンブル",
      "iab_categories": \[
        "IAB9-7"
      \]
    },
    {
      "id": "1jz",
      "name": "マッチング",
      "iab_categories": \[
        "IAB14-1"
      \]
    },
    {
      "id": "1k0",
      "name": "非営利団体",
      "iab_categories": \[
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      \]
    }
  \]
}

ここでは、categories パラメータを「Science & Education」に設定するには、iab_categories の全セット、つまり "IAB5", "IAB15" をラインアイテムに対して次のように設定する必要があります。

POST https://ads-api.x.com/8/accounts/55w3kv/line\_items?campaign\_id=f2rp3&bid\_amount\_local\_micro=5500000&name=curated-category-line-item&product\_type=MEDIA&placements=ALL\_ON\_TWITTER&objective=PREROLL_VIEWS&categories=IAB3,IAB13,IAB21

{
  "request": {
    "params": {
      "name": "curated-category-line-item",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 5500000,
      "product_type": "MEDIA",
      "objective": "PREROLL_VIEWS",
      "account_id": "55w3kv",
      "categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \],
      "campaign_id": "f2rp3"
    }
  },
  "data": {
    "bid_type": "MAX",
    "advertiser\_user\_id": 312226591,
    "name": "curated-category-line-item",
    "placements": \[
      "ALL\_ON\_TWITTER"
    \],
    "start_time": null,
    "bid\_amount\_local_micro": 5500000,
    "automatically\_select\_bid": false,
    "advertiser_domain": null,
    "target\_cpa\_local_micro": null,
    "raw_categories": \[
      "x",
      "5l",
      "9z"
    \],
    "primary\_web\_event_tag": null,
    "charge\_by": "VIEW\_3S_100PCT",
    "product\_type": "PROMOTED\_TWEETS",
    "end_time": null,
    "duration\_in\_days": null,
    "bid\_unit": "VIEW\_3S_100PCT",
    "total\_budget\_amount\_local\_micro": null,
    "objective": "PREROLL_VIEWS",
    "id": "iqwka",
    "entity_status": "ACTIVE",
    "automatic\_tweet\_promotion": null,
    "optimization": "DEFAULT",
    "frequency_cap": null,
    "android\_app\_store_identifier": null,
    "categories": \[
      "IAB3",
      "IAB13",
      "IAB21"
    \],
    "currency": "USD",
    "created_at": "2021-02-09T00:00:46Z",
    "tracking_tags": \[\],
    "ios\_app\_store_identifier": null,
    "amplify_config": {
      "auto_promote": true,
      "is_open": true
    },
    "updated_at": "2021-02-09T00:00:46Z",
    "campaign_id": "f2rp3",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

​

パブリッシャーの選択

広告主は、コンテンツカテゴリとキュレーテッドカテゴリのいずれか一方をターゲットとして選択できます。詳細は以下をご覧ください。 

注: ラインアイテムでは、キュレーテッドカテゴリかコンテンツカテゴリのどちらか一方のみをターゲットにでき、両方を同時にターゲットにすることはできません。 

​

キュレーテッドカテゴリ

キュレーテッドカテゴリを使用すると、広告主はあらかじめ定義されたパブリッシャーのグループをターゲティングでき、GET curated_categories エンドポイントを使用して取得できます。これらのカテゴリは国ごとに定義されているため、カテゴリの country_code に基づいて、ラインアイテムが適切な国をターゲティングする必要があります。

これらのカテゴリのいずれかを利用するには、以下の手順を記載されている順番どおりに実行する必要があります。

1. ラインアイテムが、キュレーテッドカテゴリの country_code に基づいて適切な国をターゲティングしている必要があります
2. POST line_item_curated_categories エンドポイントを使用して、ラインアイテムを特定の curated_category_id に関連付ける必要があります。 

注: ラインアイテムをキュレーテッドカテゴリに関連付けると、denylist に登録できるパブリッシャー数は 5 件に制限されます。特定のパブリッシャーを denylist するために使用する user_id の完全なリストは、GET publishers エンドポイントから取得できます。さらに、1 つのラインアイテムが同時にターゲティングできるキュレーテッドカテゴリは 1 つのみです。

次の例は、US でのみ利用可能なキュレーテッドカテゴリ id: b0xt を、前の手順で作成したラインアイテムに関連付ける方法を示しています。

まず、ラインアイテムのターゲティング条件を値 96683cc9126741d に設定します。

GET https://ads-api.x.com/8/targeting\_criteria/locations?country\_code=US&location_type=COUNTRIES

{
  "data": \[
    {
      "name": "United States",
      "country_code": "US",
      "location_type": "COUNTRIES",
      "targeting_value": "96683cc9126741d1",
      "targeting_type": "LOCATION"
    }
  \],
  "request": {
    "params": {
      "location_type": "COUNTRIES",
      "country_code": "US"
    }
  },
  "next_cursor": null
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwka",
      "targeting_type": "LOCATION",
      "targeting_value": "96683cc9126741d1",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "United States",
      "raw_negated": false,
      "raw\_targeting\_value": "2",
      "id": "rv9hmc",
      "raw\_targeting\_type": "GEO",
      "raw\_operator\_type": "EQUAL_TO",
      "location_type": "COUNTRIES",
      "operator_type": "EQ",
      "created_at": "2021-02-09T00:06:28Z",
      "targeting_value": "96683cc9126741d1",
      "updated_at": "2021-02-09T00:06:28Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "96683cc9126741d1",
        "targeting_type": "LOCATION"
      },
      "operation_type": "Create"
    }
  \]
}

POST https://ads-api.x.com/8/accounts/55w3kv/line\_item\_curated\_categories?line\_item\_id=iqwka&curated\_category_id=9ddrgesiap6o

{
  "request": {
    "params": {
      "curated\_category\_id": "9ddrgesiap6o",
      "line\_item\_id": "iqwka",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "line\_item\_id": "iqwka",
    "curated\_category\_id": "9ddrgesiap6o",
    "id": "xq",
    "created_at": "2021-03-30T17:26:42Z",
    "updated_at": "2021-03-30T17:26:42Z",
    "deleted": false
  }
}

​

コンテンツカテゴリ

コンテンツカテゴリ (Standard Categories とも呼ばれます) は、GET curated_categories エンドポイントから取得できます。これらのカテゴリは、バッチターゲティング条件エンドポイントを使用してラインアイテムのターゲットとして指定できます。次の例では、特定のコンテンツカテゴリ id: sr (「News & Current Events」に対応) を選択し、それをラインアイテムに適用する方法を示します。

Note: GET curated_categories レスポンスに含まれる iab_categories の全セットを、ターゲティング条件エンドポイント経由で必ずターゲット指定する必要があります。そうしない場合は検証エラーが発生します。 

GET https://ads-api.x.com/8/content_categories
{
      "name": "News & Current Events",
      "id": "sr",
      "iab_categories": \[
        "IAB12",
        "IAB14"
      \],
      "publishers\_in\_last\_thirty\_days": 124,
      "videos\_monetized\_in\_last\_thirty_days": 5429
    }
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB12",
      "operator_type": "EQ"
    }
  },
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB14",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwls",
      "name": "News",
      "raw_negated": false,
      "raw\_targeting\_value": "5h",
      "id": "saib9p",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB12",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    },
    {
      "line\_item\_id": "iqwls",
      "name": "Society",
      "raw_negated": false,
      "raw\_targeting\_value": "5y",
      "id": "saib9q",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB14",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB12",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB14",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    }
  \]
}

アカウントのメディア (動画) をラインアイテムに関連付ける

POST accounts/:account_id/media_creatives エンドポイントを使用して、この動画を広告グループに関連付けます。

POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives
line\_item\_id=4bii5&account\_media\_id=knb

{
 "data":{
   "account\_media\_id":"74g",
   "approval_status":"ACCEPTED",
   "created_at":"2016-02-11T22:23:23Z",
   "deleted":false,
   "id":"qeq",
   "landing_url":null,
   "line\_item\_id":"4bii5",
   "serving_status":"ACTIVE",
   "updated_at":"2016-02-11T22:23:23Z"
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "account\_media\_id":"knb"
   }
 }
}

​

CTA とリンク先 URL を設定する

X 上のほとんどの他のキャンペーンと異なり、VIDEO_VIEWS_PREROLL 目的では Promoted Tweets や Cards は使用されない点に注意が必要です。代わりに、動画クリエイティブは広告グループ (ラインアイテム) に関連付けられ、CTA 情報は preroll_call_to_action エンティティに関連付けられます。POST accounts/:account_id/preroll_call_to_action エンドポイントを使用して、ボタンの CTA とリンク先 URL を設定できます。

POST https://ads-api.x.com/8/accounts/55w3kv/preroll\_call\_to_action
line\_item\_id=4bii5&call\_to\_action=VISIT\_SITE&call\_to\_action\_url=https%3A%2F%2Fx.com%2FAdsAPI

{
 "data":{
   "id":"aaa111",
   "line\_item\_id":"4bii5",
   "call\_to\_action":"WATCH_NOW",
   "call\_to\_action_url":"https://x.com/AdsAPI",
   "created_at":"2016-02-11T22:23:23Z",
   "updated_at":"2016-02-11T22:23:23Z",
   "deleted":false
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "call\_to\_action":"VISIT_SITE",
     "call\_to\_action_url":"https://x.com/AdsAPI"
   }
 }
}

​

ターゲティング条件を設定する

プレロール動画広告に利用されるターゲティング条件は、バッチターゲティング条件エンドポイント POST batch/accounts/:account_id/targeting_criteria でのみ使用できます。

CONTENT_PUBLISHER_USER を除外ターゲティングとして使用し、広告が特定のユーザーと組み合わされないようにします。除外したいハンドル (@ユーザー名) の X の user_id または publisher_user_id を指定してください。

GET publishers エンドポイントを使用すると、コンテンツカテゴリで除外する user_id のリストを取得できます。GET curated_categories のレスポンスで返される publisher_user_id を利用して、キュレイテッドカテゴリ向けの同様の除外リストを取得することもできます。

注: キュレイテッドカテゴリでは最大 5 件の publisher_user_id、コンテンツカテゴリでは最大 50 件の user_id を除外できます。

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "CONTENT\_PUBLISHER_ID",
      "targeting_value": "1917731",
      "operator_type": "NE"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "realsaltlake",
      "raw_negated": true,
      "raw\_targeting\_value": "aajwo",
      "id": "sajk32",
      "raw\_targeting\_type": "CONTENT_PUBLISHER",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "NE",
      "created_at": "2021-03-30T18:02:32Z",
      "targeting_value": 17288520,
      "updated_at": "2021-03-30T18:02:32Z",
      "deleted": false,
      "targeting\_type": "CONTENT\_PUBLISHER_USER"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "NE",
        "targeting_value": "17288520",
        "targeting\_type": "CONTENT\_PUBLISHER_USER"
      },
      "operation_type": "Create"
    }
  \]
}

​

キャンペーンを開始する

キャンペーンを開始する準備ができたら、PUT accounts/:account_id/campaigns/:id を実行して一時停止を解除します。

PUT https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3? entity_status=ACTIVE

{
  "request": {
    "params": {
      "campaign_id": "f2rp3",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "ACTIVE",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "ACTIVE",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

​

アナリティクス

VIDEO_VIEWS_PREROLL キャンペーンのアナリティクスは、stats エンドポイント経由で取得できます。

​

タイムラインにおけるキーワードターゲティング

キーワードターゲティングは、キャンペーンのリーチを拡大するうえで、Promoted Tweets 製品の根幹となる機能です。タイムラインでのキーワードターゲティングにより、プラットフォームでは、X ユーザーの直近のツイートに含まれるキーワードに基づいてターゲティングを行うことができます。たとえば、広告主が順不同のキーワードの組み合わせ「plan + trip」をターゲティングしており、キャンペーン配信中にあるユーザーが「カボへの旅行の計画を立て始めたところ。おすすめはある？」とツイートした場合、そのユーザーはその後まもなく広告主の Promoted Tweet を目にする可能性があります。

​

どのように動作しますか？

TL;DR: API の観点から見ると、この変更はとてもシンプルです。タイムライン上のプロモツイートでキーワードターゲティングができるようになります。ラインアイテムの targeting_type を unordered_keywords または phrase_keywords に設定するだけです。

​

クイックスタートガイド

• ALL_ON_TWITTER または TWITTER_TIMELINE のいずれかを含むように placement を設定して、新しいラインアイテムを作成します。 POST accounts/:account_id/line_items
• 新しく作成したラインアイテム用のターゲティング条件 (targeting criteria) を、BROAD_KEYWORD を使用して作成し、キーワード値を設定します。 POST accounts/:account_id/targeting_criteria
• キーワードは PUT accounts/:account_id/targeting_criteria で更新できます。
• キャンペーンの配信が開始されたら、ラインアイテムのパフォーマンスを把握するために統計情報を取得します。 GET stats/accounts/:account_id

​

APIリファレンス

​

アカウント

​

GET accounts

認証ユーザーがアクセス権を持つ、広告配信が有効な一部またはすべてのアカウントの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts

Parameters

Name	Description
account_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを対象のアカウントIDのみに絞り込みます。 Type: string Example: 18ce54d4x5t
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	name でリソースを絞り込むための任意のクエリを指定します。 Note: 大文字小文字を区別しない前方一致で検索します。 Type: string Min, Max length: 1, 255
sort_by optional	サポートされている属性を基準に、昇順または降順でソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定されている、より低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

​

リクエスト例

GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t

レスポンス例

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
           {
             "name": "API McTestface",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": "2016-07-21T07:00:00Z",
             "id": "18ce54d4x5t",
             "created_at": "2016-07-21T22:42:09Z",
             "updated_at": "2017-07-06T16:51:04Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

​

GET accounts/:account_id

認証済みユーザーがアクセス権を持つ特定のアカウントを取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	対象となるアカウントを識別するための識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。 指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
with_deleted optional	リクエストに削除済みの結果を含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
           }
         },
         "data": {
           "name": "API McTestface",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TRAVEL",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

​

POST accounts

注意: SANDBOX のみ

サンドボックス環境で広告アカウントを作成します。

Resource URL

https://ads-api-sandbox.x.com/12/accounts

Parameters

なし

Example Request

POST https://ads-api-sandbox.x.com/12/accounts

Example Response

       {
         "request": {
           "params": {}
         },
         "next_cursor": null,
         "data": [
           {
             "name": "Sandbox account",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": null,
             "id": "gq12fh",
             "created_at": "2016-07-18T23:02:20Z",
             "updated_at": "2016-07-18T23:02:20Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

​

PUT accounts/:account_id

アカウント名および／または業種タイプを更新します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	利用対象となるアカウントの識別子です。リソースのパス内に含まれており、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。 指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
name optional	アカウントの名前です。 Type: string Example: API McTestface
industry_type optional	アカウントが関連付けられている業種です。 Type: string Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
             "name"": "API McTestface 2",
             "industry_type": "TECHNOLOGY"
           }
         },
         "data": {
           "name": "API McTestface 2",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TECHNOLOGY",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

​

DELETE accounts/:account_id

注: Sandbox 環境のみ

Sandbox 環境で広告アカウントを削除します。

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメーターです。 指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh

Example Response

       {
         "data": {
           "name": "Sandbox account",
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": null,
           "id": "gq12fh",
           "created_at": "2016-07-18T23:02:20Z",
           "updated_at": "2017-08-23T18:21:10Z",
           "approval_status": "ACCEPTED",
           "deleted": true
         },
         "request": {
           "params": {
             "account_id": "gq12fh"
           }
         }
       }

​

アカウントのApp

Postman で実行 ❯

​

GET account_apps

指定された広告アカウントに関連付けられているすべてのモバイルアプリの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/account_apps

Parameters

Name	Description
account_id required	対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
sort_by optional	対応している属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果もリクエストに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	レスポンスに total_count 属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、レート制限がより低く適用され、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps

Example Response

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
          {
            "app_store_identifier": "com.twitter.android",
            "conversion_tracking_enabled": false,
            "deep_link_pattern": "twitter://",
            "id": "4x",
            "created_at": "2019-06-20T22:36:16Z",
            "updated_at": "2021-10-19T20:05:29Z",
            "os_type": "Android",
            "deleted": false
          }
         ]
       }

​

アカウント履歴

​

GET accounts/:account_id/account_history

リクエストで指定された entity_id に対して行われた変更の概要を取得します。

注: このエンドポイントは現在ベータ版であり、許可リストへの登録が必要です。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/account_history

パラメータ

名前	説明
account_id 必須	対象アカウントの識別子。 Type: string Example: 18ce54d4x5t
count 任意	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor 任意	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
entity_type 必須	データを取得する対象のエンティティ種別。 Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id 必須	データを取得する対象の特定のエンティティ。 Type: string Example: 8u94t
start_time 必須	取得されるデータの範囲を、ISO 8601 形式で指定された開始時刻に限定します。 注: 分および秒が 0 の「1 時間単位」で指定する必要があります。 Type: string Example: 2017-05-19T07:00:00Z
end_time 必須	取得されるデータの範囲を、ISO 8601 形式で指定された終了時刻に限定します。 注: 分および秒が 0 の「1 時間単位」で指定する必要があります。 Type: string Example: 2017-05-26T07:00:00Z
user_id 任意	レスポンスを特定のユーザーに限定します。 Type: long Example: 3271358660

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "test_campaign",
            "start_time": "2021-04-02T18:59:11Z",
            "purchase_order_number": null,
            "daily_budget_amount_local_micro": 100000000,
            "end_time": null,
            "duration_in_days": null,
            "standard_delivery": true,
            "total_budget_amount_local_micro": 100000000,
            "entity_status": "ACTIVE",
            "frequency_cap": null,
            "created_at": "2021-04-02T20:55:42Z",
            "updated_at": "2021-04-02T20:55:42Z",
            "deleted": false
          },
          "change_type": "CREATE"
        }
      ]
    }

​

広告主の事業カテゴリ

​

GET advertiser_business_categories

広告主のブランドをパブリッシャーに説明するために Ad Group (line_items) で使用できる、有効な広告主ビジネス categories を取得します。

注記: これらのカテゴリは PREROLL_VIEWS という objective を持つ line_items にのみ適用され、ターゲティング条件に使用される content_categories とは別個のものです。

各 advertiser_business_categories は IAB Categories の集合を表します。PREROLL_VIEWS objective を持つ Ad Group を作成する際は、その Ad Group に 1 つまたは 2 つの advertiser_business_categories を設定する必要があります。これは、line item エンドポイントのリクエストパラメータ categories の値として、このエンドポイントから取得可能な対応する iab_categories の集合を指定することで行います。

詳細については、Video Views Preroll Objective Guide を参照してください。

Resource URL

https://ads-api.x.com/12/advertiser_business_categories

Parameters

リクエストパラメータはありません。

Example Request

GET https://ads-api.x.com/12/advertiser_business_categories

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Consumer Packaged Goods",
          "iab_categories": [
            "IAB9-26",
            "IAB9-18",
            "IAB9-29",
            "IAB9-1",
            "IAB9-8",
            "IAB9-22",
            "IAB6",
            "IAB9-5",
            "IAB9-12",
            "IAB9-11",
            "IAB9-23",
            "IAB9-14",
            "IAB4",
            "IAB9-25",
            "IAB9-17",
            "IAB23",
            "IAB9-24",
            "IAB9-13",
            "IAB16",
            "IAB9-4",
            "IAB9-9",
            "IAB9-20",
            "IAB22",
            "IAB9-28",
            "IAB9-27",
            "IAB9-16",
            "IAB9-31",
            "IAB9-3",
            "IAB9-19",
            "IAB10",
            "IAB9-2",
            "IAB9-6",
            "IAB9-21",
            "IAB9-10",
            "IAB9-15"
          ]
        },
        {
          "id": "1jm",
          "name": "Health & Pharma",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Alcohol",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Dining",
          "iab_categories": [
            "IAB8-10",
            "IAB8-8",
            "IAB8-7",
            "IAB8-15",
            "IAB8-3",
            "IAB8-4",
            "IAB8-1",
            "IAB8-16",
            "IAB8-12",
            "IAB8-13",
            "IAB8-17",
            "IAB8-11",
            "IAB8-6",
            "IAB8-9",
            "IAB8-2",
            "IAB8-14"
          ]
        },
        {
          "id": "1jp",
          "name": "Financial Services",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Retail",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Travel",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Gaming",
          "iab_categories": [
            "IAB9-30"
          ]
        },
        {
          "id": "1jt",
          "name": "Technology",
          "iab_categories": [
            "IAB19-22",
            "IAB19-13",
            "IAB19-4",
            "IAB19-33",
            "IAB19-26",
            "IAB19-3",
            "IAB19-16",
            "IAB19-9",
            "IAB19-32",
            "IAB19-25",
            "IAB19-30",
            "IAB19-36",
            "IAB19-21",
            "IAB5",
            "IAB19-12",
            "IAB19-28",
            "IAB19-17",
            "IAB19-8",
            "IAB19-7",
            "IAB19-24",
            "IAB15",
            "IAB19-11",
            "IAB19-31",
            "IAB19-20",
            "IAB19-15",
            "IAB19-1",
            "IAB19-35",
            "IAB19-29",
            "IAB19-34",
            "IAB19-23",
            "IAB19-2",
            "IAB19-5",
            "IAB19-14",
            "IAB19-27",
            "IAB19-10",
            "IAB19-19"
          ]
        },
        {
          "id": "1ju",
          "name": "Telecommunication",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Auto",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "メディア・エンターテインメント",
          "iab_categories": [
            "IAB14-8",
            "IAB14-4",
            "IAB1-5",
            "IAB14-7",
            "IAB1-7",
            "IAB17",
            "IAB14-3",
            "IAB1-1",
            "IAB12",
            "IAB1-6",
            "IAB25-1",
            "IAB1-2",
            "IAB14-2",
            "IAB14-6",
            "IAB1-3",
            "IAB1-4",
            "IAB14-5"
          ]
        },
        {
          "id": "1jx",
          "name": "Politics",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Gambling",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Dating",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Non-Profit",
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

​

オーディエンス規模の推定

POST accounts/:account_id/audience_estimate

​

キャンペーンのおおよそのオーディエンス規模を推定します。

このエンドポイントは、ターゲティング条件オブジェクトのパラメータを含む JSON オブジェクトの配列を受け付けます。必須および任意のターゲティング条件パラメータの一覧は、POST accounts/:account_id/targeting_criteria エンドポイントで確認できます。リクエストは HTTP POST で送信し、Content-Type: application/json ヘッダーを付与した JSON 本文を含める必要があります。

注意: 少なくとも 1 つのプライマリターゲティング条件を指定する必要があります。すべてのプライマリターゲティング条件の一覧は、キャンペーンターゲティングのページで確認できます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/audience_estimate

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
targeting_criteria required	ターゲティング条件オブジェクトのすべてのパラメータを含む JSON オブジェクトです。必須および任意のターゲティング条件パラメータの一覧は、POST accounts/:account_id/targeting_criteria エンドポイントで確認できます。
operator_type optional	ターゲティング条件が持つべき関係を指定します。たとえば、除外ターゲティングを設定するには operator_type=NE を使用します。 Type: enum Possible values: EQ, NE Default: EQ

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate

    {
        "targeting_criteria": [
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "nba",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "tech",
                "operator_type": "NE"
            },
            {
                "targeting_type": "LOCATION",
                "targeting_value": "96683cc9126741d1",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "14230524"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "90420314"
            }
        ]
    }

レスポンス例

    {
      "request": {
        "params": {
          "targeting_criteria": null,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "audience_size": {
          "min": 38236294,
          "max": 42261167
        }
      }
    }

​

認証済みユーザー アクセス

​

GET accounts/:account_id/authenticated_user_access

現在認証されているユーザー (access_token) の、指定した広告アカウントに対する権限を取得します。これらの権限は ads.x.com 上で表示されるものと同一です。

取りうる値は次のとおりです。

• ACCOUNT_ADMIN: キャンペーンの変更および統計の閲覧に対するフルアクセス権を持ち、ユーザーの追加・削除や設定変更も可能
• AD_MANAGER: キャンペーンの変更および統計の閲覧に対するフルアクセス権を持つが、ユーザーの追加・削除や設定変更は不可
• CREATIVE_MANAGER: クリエイティブの変更およびプレビューの閲覧が可能だが、キャンペーンの作成や変更は不可
• CAMPAIGN_ANALYST: キャンペーンおよび統計の閲覧が可能だが、キャンペーンの作成や変更は不可
• ANALYST (ads.x.com 上では「Organic Analyst」) : オーガニック分析およびオーディエンスインサイトの閲覧が可能だが、キャンペーンの作成、変更、閲覧は不可
• PARTNER_AUDIENCE_MANAGER: データパートナーオーディエンスの閲覧および変更に対する API 経由のみのアクセス権を持つが、キャンペーン、クリエイティブ、その他のオーディエンス種別へのアクセス権はなし

加えて、TWEET_COMPOSER 権限は、認証されたユーザーが広告主に代わって nullcast (「Promoted-only」) ツイートを作成できることを示します。これは ACCOUNT_ADMIN、AD_MANAGER、または CREATIVE_MANAGER 権限を持つユーザーのみに利用可能です。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access

Parameters

なし

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access

Example Response

    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

入札ルール

​

GET bidding_rules

一部またはすべての通貨に対する入札ルールを取得します。レスポンスには、最小および最大の CPE (Cost-Per-Engagement、エンゲージメント単価) の入札額が含まれます。

これらの入札ルールが変更されることは稀ですが、少なくとも月に一度は、システム側でこれらのエンドポイントから最新情報を取得することを推奨します。

Resource URL

https://ads-api.x.com/12/bidding_rules

Parameters

Name	Description
currency optional	結果をフィルタリングする通貨の種類。ISO-4217 を使用して識別します。“USD” や “EUR” のような 3 文字の文字列です。認証に使用しているユーザーに関連付けられたすべての入札ルールを取得するには、このパラメータを省略します。 Type: string Example: USD

Example Request

GET https://ads-api.x.com/12/bidding_rules?currency=USD

Example Response

    {
      "request": {
        "params": {
          "currency": "USD"
        }
      },
      "data_type": "bidding_rule",
      "data": [
        {
          "currency": "USD",
          "minimum_cpe_bid_local_micro": 10000,
          "maximum_cpe_bid_local_micro": 1000000000,
          "minimum_denomination": 10000
        }
      ],
      "total_count": 1
    }

​

キャンペーン

​

GET accounts/:account_id/campaigns

現在のアカウントに関連付けられている一部またはすべてのキャンペーンの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_ids optional	識別子のカンマ区切りリストを指定することで、レスポンスを目的のキャンペーンのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8wku2
count optional	個々のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
funding_instrument_ids optional	識別子のカンマ区切りリストを指定することで、特定の funding instrument 配下のキャンペーンのみにレスポンスを限定します。最大 200 個の ID を指定できます。 Type: string Example: lygyi
q optional	name でリソースを絞り込むための任意のクエリです。 Type: string Min, Max length: 1, 255
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	レスポンスに削除済みの結果も含めます。 Type: boolean Default: false Possible values: true, false
with_draft optional	レスポンスにドラフトのキャンペーンも含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定されている、より低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "campaign_ids": [
            "8wku2"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "test",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 10000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8wku2",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/campaigns/:campaign_id

現在のアカウントに紐づいている特定のキャンペーンを取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_id required	リクエストで操作対象としているキャンペーンを参照します。 Type: string Example: 8wku2
with_deleted optional	削除済みの結果もレスポンスに含めます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 10000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/campaigns

現在のアカウントに関連付けられた新しいキャンペーンを作成します。

注意: 1 アカウントあたりアクティブなキャンペーンのデフォルト上限は 200 件です。ただし、非アクティブなキャンペーンの数に制限はありません。この上限はアクティブなキャンペーン 8,000 件まで引き上げることができます。より高い上限を有効にするには、広告主が自分の X のアカウントマネージャーにリクエストする必要があります。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

パラメーター

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
funding_instrument_id required	キャンペーンを作成する対象となるファンディングインストゥルメントの識別子です。 Type: string Example: lygyi
name required	キャンペーン名です。最大長: 255 文字。 Type: string Example: demo
budget_optimization optional	適用する予算最適化の種類を選択します。 Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro sometimes required	キャンペーンに割り当てる 1 日あたりの予算額です。指定されたファンディングインストゥルメントに紐づく通貨が使用されます。USD の場合、$5.50 は 5500000 と表現されます。 注意: これは total_budget_amount_local_micro 以下である必要があり、ほとんどのファンディングインストゥルメントの種別で必須です。 Type: long Example: 5500000
entity_status optional	キャンペーンのステータスです。 Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number optional	予約参照番号です。請求書照合を行う際にこのフィールドを使用します。最大長: 50 文字。 Type: string Example: D00805843
standard_delivery optional	標準配信または高速配信を有効にします。標準配信と高速配信の違いについては Budget Pacing を参照してください。budget_optimization が CAMPAIGN に設定されている場合にのみ利用できます。 Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	キャンペーンに割り当てる合計予算額です。指定されたファンディングインストゥルメントに紐づく通貨が使用されます。USD の場合、$37.50 は 37500000 と表現されます。 Type: long Example: 37500000

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false

レスポンス例

    {
      "request": {
        "params": {
          "name": "demo",
          "budget_optimization": "CAMPAIGN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "standard_delivery": false,
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "demo",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "hwtbm",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/campaigns

1 回のリクエストで新しいキャンペーンを一括作成できます。

バッチリクエスト

• 現在の最大バッチサイズは 40 です。
• すべてのパラメータはリクエストボディで送信され、Content-Type として application/json が必須です。
• バッチリクエストはグループとしてまとめて失敗または成功し、エラー・成功どちらの API レスポンスでも、最初のリクエスト内のアイテムの順序が維持されます。

バッチレスポンス

バッチ API レスポンスは順序付きのアイテムのコレクションを返します。それ以外は、対応する単一アイテムのエンドポイントと構造が同一です。

バッチエラー

• リクエストレベルのエラー (例: 最大バッチサイズ超過) は、レスポンス内の errors オブジェクトに表示されます。
• アイテムレベルのエラー (例: 必須キャンペーンパラメータの未指定) は、レスポンス内の operation_errors オブジェクトに表示されます。

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/campaigns

Parameters

Name	Description
operation_type required	各アイテムに対して実行する操作の type。 Type: enum 可能な値: Create, Delete, Update
params required	キャンペーンオブジェクトのすべてのパラメータを含む JSON オブジェクト。必須および任意のキャンペーンパラメータの一覧についてはこちらを参照してください。

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"batch campaigns",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

レスポンスの例

    {
      "data": [
        {
          "name": "batch campaigns",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8yn7m",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "name": "batch campaigns",
            "funding_instrument_id": "lygyi",
            "daily_budget_amount_local_micro": 140000000,
            "entity_status": "PAUSED",
            "budget_optimization":"CAMPAIGN",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        }
      ]
    }

​

PUT accounts/:account_id/campaigns/:campaign_id

現在のアカウントに関連付けられている指定のキャンペーンを更新します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほぼすべての Advertiser API リクエストで必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_id required	リクエストで操作対象となるキャンペーンを示す参照です。 Type: string Example: 8wku2
budget_optimization optional	適用する予算最適化の種類を選択します。 Type: enum Default: CAMPAIGN Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro optional	キャンペーンに割り当てる 1 日あたりの予算額です。指定されたファンディングインストルメントに関連付けられた通貨が使用されます。USD の場合、$5.50 は 5500000 として表されます。指定しない場合、キャンペーンは合計予算と配信期間に基づいて均等に消化されます。 注: この値は total_budget_amount_local_micro 以下である必要があります。 Type: long Example: 5500000
entity_status optional	キャンペーンのステータスです。 Type: enum Possible values: ACTIVE, PAUSED
name optional	キャンペーンの名前です。最大長: 255 文字。 Type: string Example: demo
purchase_order_number optional	予約の参照番号です。このフィールドを請求書の照合作業に利用します。最大長: 50 文字。 Type: string Example: D00805843
standard_delivery optional	標準配信または加速配信を有効にします。標準配信と加速配信の詳細は Budget Pacing を参照してください。budget_optimization が CAMPAIGN に設定されている場合にのみ利用できます。 Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	キャンペーンに割り当てる合計予算額です。指定されたファンディングインストルメントに関連付けられた通貨が使用されます。USD の場合、$37.50 は 37500000 として表されます。 Type: long Example: 140000000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:53:54Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/campaigns/:campaign_id

現在のアカウントに属する指定のキャンペーンを削除します。

注意: キャンペーンの削除は取り消しできません。削除済みリソースを再度削除しようとすると、HTTP 404 が返されます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t
campaign_id required	リクエストで操作対象となるキャンペーンを参照するための値です。 Type: string Example: 8yn7m

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [],
        "servable": null,
        "purchase_order_number": null,
        "effective_status": "RUNNING",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8yn7m",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:56:35Z",
        "deleted": true
      }
    }

​

コンテンツカテゴリー

​

GET content_categories

ラインアイテムに対して targeting_criteria として設定可能な有効なコンテンツ categories をリクエストします。

各 content_category は 1 つ以上の IAB Categories にマッピングされます。これは、バッチ targeting_critera エンドポイントで targeting_type を IAB_CATEGORY に設定し、content_categories リクエストによって返される対応する iab_categories の集合を含めることで指定できます。これを行わない場合は、バリデーションエラーが発生します。

これら各コンテンツカテゴリに対するパブリッシャーの詳細は、GET publishers エンドポイントを使用して取得できます。

追加の詳細は、Video Views Pre-roll Objective Guide に記載されています。

Resource URL

https://ads-api.x.com/12/content_categories

Parameters

リクエストパラメータはありません

Example Request

GET https://ads-api.x.com/12/content_categories

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automotive (Cars, Trucks, Racing)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comedy",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Digital Creators",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Entertainment & Pop Culture",
          "id": "sm",
          "iab_categories": [
            "IAB1-1",
            "IAB1-2",
            "IAB1-3",
            "IAB1-5"
          ],
          "publishers_in_last_thirty_days": 120,
          "videos_monetized_in_last_thirty_days": 3482
        },
        {
          "name": "Financial & Business News",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Food & Drink",
          "id": "so",
          "iab_categories": [
            "IAB8-8",
            "IAB8-12",
            "IAB8-17",
            "IAB8-2",
            "IAB8-3",
            "IAB8-7",
            "IAB8-11",
            "IAB8-4",
            "IAB8-14",
            "IAB8-10",
            "IAB8-15",
            "IAB8-13",
            "IAB8-9",
            "IAB8-16",
            "IAB8-6",
            "IAB8-1"
          ],
          "publishers_in_last_thirty_days": 24,
          "videos_monetized_in_last_thirty_days": 516
        },
        {
          "name": "ライフスタイル(ファッション、旅行、ウェルネス)",
          "id": "sp",
          "iab_categories": [
            "IAB16",
            "IAB9-21",
            "IAB9-4",
            "IAB9-25",
            "IAB9-8",
            "IAB4",
            "IAB9-3",
            "IAB9-15",
            "IAB7",
            "IAB6",
            "IAB9-11",
            "IAB9-16",
            "IAB9-7",
            "IAB9-20",
            "IAB9-24",
            "IAB9-17",
            "IAB9-12",
            "IAB9-31",
            "IAB9-27",
            "IAB10",
            "IAB9-10",
            "IAB9-23",
            "IAB9-6",
            "IAB9-18",
            "IAB9-13",
            "IAB9-1",
            "IAB9-28",
            "IAB20",
            "IAB9-5",
            "IAB9-26",
            "IAB22",
            "IAB23",
            "IAB9-9",
            "IAB9-22",
            "IAB18",
            "IAB9-2",
            "IAB9-19",
            "IAB9-14",
            "IAB9-29"
          ],
          "publishers_in_last_thirty_days": 67,
          "videos_monetized_in_last_thirty_days": 2412
        },
        {
          "name": "Music",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "News & Current Events",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politics",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Science & Education",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Sports",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "Technology",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Television",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports & Video Games",
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

​

キュレーション済みカテゴリー

​

GET accounts/:account_id/curated_categories

指定された country_codes に対して利用可能なキュレイテッドカテゴリのリストを取得します。

各 curated_category は、レスポンス内の country_codes によって指定される特定の国でのみ利用可能です。

詳細は Video Views Pre-roll Objective ガイドを参照してください。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで、通常は必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
country_codes required	カンマ区切りの 2 文字の ISO 国コードのリストを指定して、レスポンスを希望する国のみに絞り込みます。最大 200 件まで指定できます。 Type: string Example: US
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US

Example Response

{
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "バスケットボール",
          "description": "大学チーム、プロチーム、シーズン中およびオフシーズンのバスケットボール動画を共有するトップスポーツメディアアカウントを含む、日々の最高のバスケットボールコンテンツと並んで配信されます。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20265254",
            "378174762",
            "900368808",
            "18939563",
            "18371803",
            "18360370",
            "770658432928079872",
            "11026952",
            "37085464",
            "16212685",
            "57422635",
            "281669945",
            "7117962",
            "23065057",
            "41688179",
            "29779226",
            "900280416",
            "364460082",
            "902030382",
            "19409270",
            "19077044",
            "18139461",
            "14992591",
            "66753565",
            "667563",
            "16727749",
            "40941404",
            "18481113",
            "791598918",
            "16201775",
            "15900167",
            "45891626",
            "191894553",
            "2181233851",
            "34352904",
            "171483987",
            "454122399",
            "57415242",
            "19263978",
            "902089998",
            "423540866",
            "2715223320",
            "22185437",
            "17292143",
            "55590247",
            "66757066",
            "22642626",
            "41604618",
            "87275465",
            "22643259",
            "32414973",
            "73406718",
            "20346956",
            "413422891",
            "45412765",
            "19537303",
            "459511725",
            "30954864",
            "21308488",
            "18552281",
            "19924520",
            "24903350",
            "851142163",
            "26270913",
            "20444254",
            "26074296",
            "6395222",
            "15537451",
            "28672101",
            "38053254",
            "24925573",
            "19564719",
            "18164425",
            "22815383",
            "20196159"
          ],
          "id": "929wbl6ymlfk",
          "created_at": "2019-11-08T21:12:47Z",
          "updated_at": "2021-03-09T20:36:44Z",
          "videos_monetized_in_last_thirty_days": 2446
        },
        {
          "name": "ゲーミングパーソナリティ",
          "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "90779436",
            "268270621",
            "567167802",
            "246596682",
            "474919140",
            "284422688",
            "185909682",
            "4767225325",
            "2559865245",
            "186888760",
            "161418822",
            "141021153",
            "352881953",
            "1117931702",
            "146556805",
            "357294577",
            "234526497",
            "266687361",
            "214201922",
            "9451052",
            "2163885564",
            "2231422037",
            "116952434",
            "399909209",
            "15993650",
            "974356091193741312",
            "210839744",
            "2313002094",
            "159916388",
            "3258981481",
            "231992478",
            "182236262",
            "386884916",
            "22705686",
            "4140881832",
            "995979576",
            "2244953047",
            "311775629",
            "98821255",
            "2733210014",
            "2741078150"
          ],
          "id": "94ngssfrr01x",
          "created_at": "2019-12-02T20:45:12Z",
          "updated_at": "2021-03-09T20:18:13Z",
          "videos_monetized_in_last_thirty_days": 448
        },
        {
          "name": "野球",
          "description": "大学チーム、プロチーム、主要な野球報道を共有するトップスポーツメディアアカウントを含む、日々の最高の野球コンテンツと並んで配信されます。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "22016177",
            "22798877",
            "52803520",
            "20710218",
            "423532170",
            "28603812",
            "41144996",
            "22819823",
            "39389304",
            "252273678",
            "123307490",
            "2319354187",
            "41488578",
            "37947138",
            "302066953",
            "159143990",
            "35006336",
            "53178109",
            "40918816",
            "39682297",
            "39397148",
            "39419180",
            "53197137",
            "52863923",
            "21407926",
            "31164229",
            "19607400",
            "39392910",
            "241544156",
            "43024351",
            "37837907",
            "165764237",
            "69117905",
            "87673496",
            "23043294",
            "52824038",
            "52861612",
            "33137450",
            "30008146",
            "39367703",
            "21436663",
            "188575356",
            "40931019",
            "41468683",
            "40927173",
            "172742915"
          ],
          "id": "9lav5usxfmdc",
          "created_at": "2020-05-18T20:20:27Z",
          "updated_at": "2021-03-09T20:37:46Z",
          "videos_monetized_in_last_thirty_days": 190
        },
        {
          "name": "eスポーツチーム",
          "description": "Run next to the programming from the world’s best esports teams, covering both in-event coverage and other year-round complimentary programming.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "フットボール",
          "description": "大学チーム、プロチーム、シーズン中・オフシーズンのフットボール動画を共有するトップスポーツメディアアカウントなど、日常的なフットボールコンテンツの最高峰の横に配信されます。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21790466",
            "53103297",
            "23642374",
            "817416193854283776",
            "43403778",
            "24179879",
            "26813914",
            "36375662",
            "33587536",
            "180884045",
            "16332223",
            "27902825",
            "180503626",
            "44468807",
            "18336787",
            "818431566",
            "22146282",
            "31126587",
            "40358743",
            "35865630",
            "16347506",
            "72665816",
            "33583496",
            "389038362",
            "36155311",
            "227342532",
            "2151130166",
            "26791995",
            "44666348",
            "24109979",
            "31504542",
            "713143",
            "423536031",
            "25545388",
            "59471027",
            "706923475",
            "19383279",
            "8824902",
            "1655877529",
            "18734310",
            "240734425",
            "17076218",
            "47964412",
            "2802184770",
            "19426729",
            "56443153",
            "23508439",
            "25084916",
            "764347046",
            "19853312",
            "348590880"
          ],
          "id": "8tujg1lvi8sn",
          "created_at": "2019-08-15T20:48:51Z",
          "updated_at": "2021-03-09T20:34:13Z",
          "videos_monetized_in_last_thirty_days": 254
        },
        {
          "name": "男性向けカルチャー＆ライフスタイル",
          "description": "フォロワープロフィールに基づいてキュレーションされたアカウントセットのコンテンツの横に配信され、テクノロジー、ニュース、ライフスタイルコンテンツを共有するトップアカウントを含む、男性中心のオーディエンスへのリーチを支援します。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "17764377",
            "61933836",
            "28370738",
            "3224616765",
            "22819823",
            "18927441",
            "734826612684783616",
            "14372486",
            "7157132",
            "15764136",
            "590316679",
            "7302282",
            "895014043932540928",
            "7517222",
            "3489420013",
            "14063426",
            "72665816",
            "214201922",
            "14980903",
            "22199141",
            "21272440",
            "25319414",
            "119593082",
            "4760694445",
            "765905855195803648",
            "238431491",
            "22178780",
            "241544156",
            "25093616",
            "16877611",
            "22146985",
            "368703433",
            "14342661",
            "415605847",
            "2181233851",
            "890891",
            "15764001",
            "614754689",
            "18479513",
            "23508439",
            "348590880"
          ],
          "id": "8tujj1ep7t34",
          "created_at": "2019-08-15T20:49:47Z",
          "updated_at": "2021-03-09T20:39:00Z",
          "videos_monetized_in_last_thirty_days": 1330
        },
        {
          "name": "女性向けカルチャー＆ライフスタイル",
          "description": "フォロワープロフィールに基づいてキュレーションされたアカウントセットのコンテンツの横に配信され、ポップカルチャー、ニュース、ライフスタイルコンテンツを共有するトップアカウントを含む、女性中心のオーディエンスへのリーチを支援します。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "23482952",
            "20177423",
            "19074134",
            "15566901",
            "32469566",
            "19784831",
            "16145224",
            "16932962",
            "14934818",
            "29730065",
            "24190981",
            "30278532",
            "15846407",
            "24994219",
            "23993734",
            "40965341",
            "16312576",
            "75094638",
            "549673665",
            "18806753",
            "75306892",
            "1482663290",
            "31181674",
            "971407531972186112",
            "4020532937",
            "25087685",
            "22515362",
            "80943051",
            "19247844",
            "15279429",
            "16824090",
            "20710809",
            "979831113655996416",
            "32432308",
            "19472585",
            "25589776",
            "739963476370673665",
            "20188834",
            "926269727663673349"
          ],
          "id": "8tujl1p3yn0g",
          "created_at": "2019-08-15T20:50:24Z",
          "updated_at": "2021-03-09T20:17:53Z",
          "videos_monetized_in_last_thirty_days": 1365
        },
        {
          "name": "明るく楽しい",
          "description": "X上で一貫してポジティブで心地よいコンテンツと会話を生み出してきた量に基づいてキュレーションされたアカウントリストの横に配信されます。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20177423",
            "22449367",
            "9695312",
            "19074134",
            "4805771380",
            "32469566",
            "1212860112047460352",
            "16402507",
            "16932962",
            "14934818",
            "17446621",
            "29730065",
            "15846407",
            "1604444052",
            "180066380",
            "16312576",
            "549673665",
            "18806753",
            "16211434",
            "545336345",
            "971407531972186112",
            "4020532937",
            "833612154",
            "22515362",
            "20710809",
            "32432308",
            "774311630",
            "3073349892",
            "926269727663673349"
          ],
          "id": "9fg8gmz96qdg",
          "created_at": "2020-03-20T19:37:44Z",
          "updated_at": "2021-03-09T19:57:40Z",
          "videos_monetized_in_last_thirty_days": 1395
        },
        {
          "name": "サッカー",
          "description": "大学チーム、プロチーム、主要なサッカー報道を共有するトップスポーツメディアアカウントなど、日常的なサッカーコンテンツの最高峰の横に配信されます。",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21677316",
            "20636347",
            "4704552148",
            "14573900",
            "22556296",
            "1415791555",
            "107146095",
            "17288520",
            "213474069",
            "17493398",
            "44990136",
            "452155423",
            "17744542",
            "16303450",
            "2841146601",
            "2413176055",
            "29739264",
            "38580532",
            "953476292913106945",
            "27092557",
            "86356439",
            "34613288",
            "3170659367",
            "119593082",
            "73412535",
            "627586654",
            "15891449",
            "23011345",
            "96951800",
            "15997022",
            "16960789",
            "21919642",
            "102965285",
            "17224076",
            "36432200",
            "1410055968"
          ],
          "id": "9ddrgesiap6o",
          "created_at": "2020-02-28T22:43:26Z",
          "updated_at": "2021-01-26T17:54:55Z",
          "videos_monetized_in_last_thirty_days": 421
        }
      ],
      "total_count": 9
    }

​

GET accounts/:account_id/curated_categories/:curated_category_id

特定の curated_category_id の詳細を取得します。

各 curated_category は、レスポンスの country_codes で指定された特定の国でのみ利用できます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
curated_category_id required	リクエストで操作対象となる Curated Category への参照です。 Type: string Example: 9ddrgesiap6o

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "id": "9ddrgesiap6o",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "Soccer",
        "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
        "country_codes": [],
        "publisher_user_ids": [
          "21677316",
          "20636347",
          "4704552148",
          "14573900",
          "22556296",
          "1415791555",
          "107146095",
          "17288520",
          "213474069",
          "17493398",
          "44990136",
          "452155423",
          "17744542",
          "16303450",
          "2841146601",
          "2413176055",
          "29739264",
          "38580532",
          "953476292913106945",
          "27092557",
          "86356439",
          "34613288",
          "3170659367",
          "119593082",
          "73412535",
          "627586654",
          "15891449",
          "23011345",
          "96951800",
          "15997022",
          "16960789",
          "21919642",
          "102965285",
          "17224076",
          "36432200",
          "1410055968"
        ],
        "id": "9ddrgesiap6o",
        "created_at": "2020-02-28T22:43:26Z",
        "updated_at": "2021-01-26T17:54:55Z",
        "videos_monetized_in_last_thirty_days": 421
      }
    }

​

機能

​

GET accounts/:account_id/features

この広告アカウントで利用可能な、付与済み機能のコレクションを取得します。機能は説明的な feature key で示され、ベータ版またはその他の限定リリースとして導入され、かつ Ads API で利用可能な場合にのみ、このエンドポイントで公開されます。これらの条件を満たさない機能は、このエンドポイントでは公開されません。

注記: このエンドポイントは、ベータ版リリースに対するクライアントのアクセス状況の可視性を高めることで、Ads API エコシステムの開発を支援することを目的としています。API 開発者が、広告主に代わって機能へのアクセスをリクエストすることはできません。これらのリクエストは、広告主が担当の X アカウントマネージャーに対してのみ行うことができます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/features

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで、原則として必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
feature_keys optional	特定の feature key を指定して検索できるオプションのパラメータです。リクエストには複数のキーをカンマ区切りで含めることができます。 注記: 応答には、このアカウントからアクセス可能な機能のみが含まれます。 型: enum 取りうる値: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        "CITY_TARGETING",
        "CONVERSATION_CARD",
        "PROMOTED_MEDIA_POLLS",
        "REACH_AND_FREQUENCY_ANALYTICS",
        "REACH_FREQUENCY_CAP",
        "UNIVERSAL_LOOKALIKE"
      ]
    }

​

POST accounts/:account_id/features

SANDBOX のみ

sandbox アカウントに機能 (feature) を追加します。

最新のアカウント機能 (account feature) の一覧は、GET accounts/:account_id/features エンドポイントから取得できます。

リソース URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: gq180y
feature_keys required	アカウントに追加するアカウント機能のカンマ区切りリストです。 Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

リクエスト例

POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "VALIDATED_AGE_TARGETING"
          ]
        }
      },
      "data": [
        "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE",
        "AWARENESS_OBJECTIVE",
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VALIDATED_AGE_TARGETING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

​

DELETE accounts/:account_id/features

SANDBOX 限定

サンドボックスアカウントから機能を削除します。

最新のアカウント機能一覧は、GET accounts/:account_id/features エンドポイントから取得できます。

リソース URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: gq180y
feature_keys required	アカウントから削除するアカウント機能のコンマ区切りリストです。 Type: enum Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

リクエスト例

DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "PREROLL_VIEWS_OBJECTIVE"
          ]
        }
      },
      "data": [
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

​

ファンディングインストルメント

​

GET accounts/:account_id/funding_instruments

現在のアカウントに関連付けられている一部またはすべての資金手段の詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments

Parameters

Name	Description
account_id required	レバレッジアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	個別のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
funding_instrument_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを指定した資金手段のみに限定します。最大 200 個の ID を指定できます。 Type: string Example: lygyi
sort_by optional	サポートされている属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 注: このパラメータと cursor は排他的です。 注: total_count を含むリクエストはレート制限がより厳しくなり、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "start_time": "2016-07-22T04:24:04Z",
          "description": "Visa ending in 0650",
          "credit_limit_local_micro": 200000000,
          "end_time": null,
          "id": "lygyi",
          "entity_status": "ACTIVE",
          "account_id": "18ce54d4x5t",
          "reasons_not_able_to_fund": [],
          "io_header": null,
          "currency": "USD",
          "funded_amount_local_micro": 645940000,
          "created_at": "2016-07-22T04:24:04Z",
          "type": "CREDIT_CARD",
          "able_to_fund": true,
          "updated_at": "2017-04-05T00:25:13Z",
          "credit_remaining_local_micro": null,
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/funding_instruments/:funding_instrument_id

現在のアカウントに関連付けられている特定の資金元 (funding instrument) を取得します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id

パラメータ

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
funding_instrument_id required	リクエスト内で操作対象となる資金元 (funding instrument) への参照です。 Type: string Example: lygyi
with_deleted optional	削除済みの結果も含めて取得します。 Type: boolean Default: false Possible values: true, false

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi

レスポンス例

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa ending in 0650",
        "credit_limit_local_micro": 200000000,
        "end_time": null,
        "id": "lygyi",
        "entity_status": "ACTIVE",
        "account_id": "18ce54d4x5t",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 645940000,
        "created_at": "2016-07-22T04:24:04Z",
        "type": "CREDIT_CARD",
        "able_to_fund": true,
        "updated_at": "2017-04-05T00:25:13Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      }
    }

​

POST accounts/:account_id/funding_instruments

SANDBOX 環境限定

sandbox 環境で funding instrument を作成します。

sandbox funding instrument を使用しても、課金が発生するリスクはありません。

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: gq1844
currency required	通貨。ISO-4217 で定義されたコードで指定します。 Type: string Example: USD
start_time required	funding instrument が有効になり使用可能になる日時。ISO 8601 で表現します。 Type: string Example: 2017-05-19T07:00:00Z
type required	作成する funding instrument の種別です。 Type: enum Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	funding instrument が無効になる日時。ISO 8601 で表現します。 Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	この funding instrument に対して利用可能な総クレジット額。 Note: 一部の funding instrument の種別にのみ適用されます。 Type: long Example: 37500000
funded_amount_local_micro optional	この funding instrument に割り当てられた総予算額。 Note: 一部の funding instrument の種別にのみ適用されます。 Type: long Example: 37500000

Example Request

POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000

Example Response

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(支払い方法がまだ設定されていません)",
        "credit_limit_local_micro": null,
        "end_time": "2018-01-10T00:00:00Z",
        "id": "hxtet",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 140000000000,
        "created_at": "2017-09-09T05:23:28Z",
        "type": "INSERTION_ORDER",
        "able_to_fund": true,
        "updated_at": "2017-09-09T05:23:28Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      },
      "request": {
        "params": {
          "start_time": "2017-07-10T00:00:00Z",
          "end_time": "2018-01-10T00:00:00Z",
          "account_id": "gq1844",
          "currency": "USD",
          "funded_amount_local_micro": 140000000000,
          "type": "INSERTION_ORDER"
        }
      }
    }

​

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id

SANDBOX 環境のみ

Sandbox 環境で資金ソースを削除します。

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: gq1844
funding_instrument_id required	リクエストで操作対象となる資金ソースへの参照です。 Type: string Example: hxt82

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82

Example Response

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(no payment method has been set up yet)",
        "credit_limit_local_micro": 500000000,
        "end_time": null,
        "id": "hxt82",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [
          "DELETED"
        ],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": null,
        "created_at": "2017-08-30T19:23:47Z",
        "type": "CREDIT_CARD",
        "able_to_fund": false,
        "updated_at": "2017-09-09T02:08:30Z",
        "credit_remaining_local_micro": null,
        "deleted": true
      },
      "request": {
        "params": {
          "funding_instrument_id": "hxt82",
          "account_id": "gq1844"
        }
      }
    }

​

IAB カテゴリ

​

GET iab_categories

広告グループ (line_items) で使用可能な categories を取得します。

Resource URL

https://ads-api.x.com/12/iab_categories

Parameters

Name	Description
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページのカテゴリを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: gc-ddf4a
with_total_count optional	レスポンス属性 total_count を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストはレート制限がより低くなり、現在 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/iab_categories?count=2

Example Response

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts & Entertainment"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Books & Literature"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

​

ラインアイテム

​

GET accounts/:account_id/line_items

現在のアカウントに関連付けられている一部またはすべてのラインアイテムの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_ids optional	カンマ区切りの識別子リストを指定することで、特定のキャンペーン配下のラインアイテムのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8gdx6
count optional	個々のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳しくは Pagination を参照してください。 Type: string Example: 8x7v00oow
funding_instrument_ids optional	カンマ区切りの識別子リストを指定することで、特定の資金源 (funding instruments) 配下のラインアイテムのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: lygyi
line_item_ids optional	カンマ区切りの識別子リストを指定することで、特定のラインアイテムのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8v7jo
q optional	name によってリソースを絞り込むための任意のクエリです。 Type: string Min, Max length: 1, 255
sort_by optional	サポートされている属性で昇順または降順にソートします。詳しくは Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_draft optional	下書きキャンペーンの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は同時には指定できません。 Note: total_count を含むリクエストはレート制限がより厳しくなり、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "itttx"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": "li-18",
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2021-02-16T00:00:00Z",
          "bid_amount_local_micro": 320000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "itttx",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2021-02-23T23:37:54Z",
          "ios_app_store_identifier": null,
          "updated_at": "2022-06-01T02:01:18Z",
          "campaign_id": "f4z6x",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/line_items/:line_item_id

現在のアカウントに関連付けられている特定のラインアイテムを取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストにおいて、通常は必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムを参照するための値です。 Type: string Example: 8v7jo
with_deleted optional	リクエストの結果に削除済みのものも含めます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "itttx",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": "li-18",
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2021-02-16T00:00:00Z",
        "bid_amount_local_micro": 320000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "funding_instrument_id": "lygyi",
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "itttx",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2021-02-23T23:37:54Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-01T02:01:18Z",
        "campaign_id": "f4z6x",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

POST accounts/:account_id/line_items

現在のアカウントに属する指定されたキャンペーンに関連付けられたラインアイテムを作成します。

1 つのキャンペーン内のすべてのラインアイテムは、同じ product_type と objective でなければなりません。

PROMOTED_ACCOUNT の product_type を使用する場合、line_item にツイートを関連付けると、標準的な PROMOTED_ACCOUNT のプレースメントに加えて、モバイルでのタイムライン上のプレースメントが追加されます。

android_app_store_identifier または ios_app_store_identifier のいずれかを設定すると、プロモーション対象のモバイルアプリに一致するターゲティング条件がラインアイテムに自動的に追加されます。たとえば、ios_app_store_identifier を指定すると、iOS に対する PLATFORM ターゲティング条件 が追加されます。

注: キャンペーンごとのラインアイテム数は最大 100 個、すべてのキャンペーンを合計したアクティブなラインアイテム数は最大 256 個です。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/line_items

パラメーター

名前	説明
account_id 必須	利用するアカウントの識別子です。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで、通常は必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_id 必須	ラインアイテムを作成するキャンペーンの識別子。 Type: string Example: 8slvg
end_time 必須	ISO 8601 で表現された、ラインアイテムの配信が終了する日時。 Type: string Example: 2017-10-05T00:00:00Z
objective 必須	このラインアイテムのキャンペーンの目的。 Type: enum 取り得る値: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements 必須	このラインアイテムを表示する掲載面。カンマ区切りの placement 値のリストを指定してください。 Type: enum Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT,TWITTER_PROFILE, TWITTER_REPLIES, TWITTER_SEARCH, TWITTER_TIMELINE
product_type 必須	このラインアイテムに含まれるプロモーションプロダクトのtype。 Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time 必須	line item の配信開始日時を ISO 8601 形式で表したもの。 Type: string Example: 2017-07-05T00:00:00Z
advertiser_domain 場合により必須	この広告主のウェブサイトのドメイン (プロトコル部分を除く) です。 注: line item の placement が PUBLISHER_NETWORK に設定されている場合に必須です。 Type: string Example: x.com
android_app_store_identifier 場合により必須	プロモーション対象アプリケーションの Google Play ストア識別子です。 注: APP_INSTALLS と APP_ENGAGEMENTS の目的では、少なくとも 1 つのアプリストア識別子 (android_app_store_identifier または ios_app_store_identifier のいずれか) を設定する必要があります。 Type: string Example: com.twitter.android
bid_amount_local_micro 場合により必須	このラインアイテムに設定する入札額。指定されたファンディングインストルメントに対応する通貨が使用されます。USD の場合、$5.50 は 5500000 として表現されます。 Note: bid_strategy が MAX または TARGET のいずれかに設定されている場合に必須です。 Note: 0 より大きい値のみ指定できます。 Type: long Example: 5500000
categories 条件によっては必須	この広告主に関連する IAB カテゴリです。 GET iab_categories を参照してください。 注記: line item の placement が PUBLISHER_NETWORK に設定されている場合に必須です。 Type: string Example: IAB3-1
ios_app_store_identifier 場合によっては必須	プロモーション対象アプリケーションの Apple App Store の ID の数値部分。 Note: APP_INSTALLS と APP_ENGAGEMENTS の目標では、少なくとも 1 つの app store ID (android_app_store_identifier または ios_app_store_identifier のいずれか) を設定する必要があります。 Type: string Example: 333903271
primary_web_event_tag 場合により必須	主要な Web イベントタグの識別子です。このラインアイテムに関連するキャンペーンのエンゲージメントを、より正確にトラッキングできるようにします。 注: ラインアイテムの goal が WEBSITE_CONVERSIONS に設定されている場合は必須です。 Type: string Example: nvo4z
advertiser_user_id 任意	PREROLL_VIEWS 広告をプロモーションしているハンドルの X ユーザーID です。一部のクライアントアプリケーションでのみ、このパラメーターを使用できます。 Type: string Example: 312226591
audience_expansion 任意	既にターゲティングしているユーザーに類似したユーザーも対象にすることで、キャンペーンのリーチを拡大するために使用されます。 注: デフォルトでは、拡張は適用されません。 Type: enum Possible values: BROAD, DEFINED, EXPANDED
bid_strategy 任意	入札方式。 AUTO は、1 日あたりの予算とキャンペーンの配信期間に基づいて入札を自動的に最適化します。 MAX は許可される入札額の上限を設定し、objective が REACH または FOLLOWERS に設定されている場合は 利用できません。 TARGET は、指定された bid_amount_local_micro の 20% 以内となるように 1 日あたりの平均入札額を調整し、objective が REACH、FOLLOWERS、または WEBSITE_CLICKS に設定されている場合に利用できます。 注記: AUTO に設定されている場合、bid_amount_local_micro は無視されます。 注記: デフォルト値は objective に基づきます。 Type: enum Possible values: AUTO, MAX, TARGET
duration_in_days 任意	frequency_cap が適用される期間 (日数) 。 Type: int 取りうる値: 1, 7, 30
entity_status 任意	ラインアイテムのステータス。 Type: enum デフォルト: ACTIVE 取り得る値: ACTIVE, DRAFT, PAUSED
frequency_cap 任意	1人のユーザーに対して広告を配信できる最大回数。 注: REACH、ENGAGEMENTS、VIDEO_VIEWS、PREROLL_VIEWS のオブジェクティブでのみサポートされます。 Type: int Example: 5
goal 任意	このラインアイテムで使用する最適化設定です。 APP_PURCHASES オプションは APP_INSTALL 目的で利用できます。APP_CLICKS および APP_INSTALLS オプションは APP_INSTALL と APP_ENGAGEMENTS の両方の目的で利用でき、サポート対象の MACT パートナー の利用が必要となる場合があります。 SITE_VISITS オプションは WEBSITE_CLICKS 目的でのみ利用できます。 注記: 目的に基づくデフォルト値です。 型: enum 可能な値: APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name 任意	このラインアイテムの名称。 Type: string 例: demo 最小／最大の長さ: 1, 255
pay_by 任意	このラインアイテムの課金の基準となる単位です。この設定を変更できるのは、APP_INSTALLS objective を使用しているラインアイテムのみです。 注意: デフォルトの pay_by は、キャンペーンの objective とラインアイテムの入札単位に基づいて自動的に設定されます。 APP_INSTALLS ゴールは、APP_CLICK と IMPRESSION の両方の値をサポートします。IMPRESSION がデフォルト値です。 LINK_CLICKS ゴールは、LINK_CLICK と IMPRESSION の両方の値をサポートします。IMPRESSION がデフォルト値ですが、bid_strategy に TARGET を設定する場合はサポートされません。 SITE_VISITS ゴールは IMPRESSION の値をサポートします。 Type: enum Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery 任意	標準配信または高速配信を有効にします。標準配信と高速配信の詳細については、Budget Pacing を参照してください。この設定は、親キャンペーンの budget_optimization が LINE_ITEM に設定されている場合にのみ使用できます Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro 任意	ラインアイテムに割り当てられる合計予算額です。指定されたファンディングインストルメントに対応する通貨が使用されます。USD の場合、$37.50 は 37500000 として表されます。 Type: long Example: 37500000
daily_budget_amount_local_micro 場合によっては必須	キャンペーンに割り当てられる 1 日あたりの予算額です。指定されたファンディングインストルメントに関連付けられている通貨が使用されます。USD の場合、$5.50 は 5500000 として表されます。指定しない場合、キャンペーンは合計予算およびキャンペーンのフライト期間に基づいて予算を均等に消化します。親キャンペーンの budget_optimization が LINE_ITEM に設定されている場合にのみ利用できます。 注記: この値は total_budget_amount_local_micro 以下である必要があります。 Type: long Example: 5500000

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15

レスポンス例

    {
      "request": {
        "params": {
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2022-06-15T00:00:00Z",
          "bid_amount_local_micro": 3210000,
          "daily_budget_amount_local_micro": 1000000,
          "product_type": "PROMOTED_TWEETS",
          "objective": "ENGAGEMENTS",
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t",
          "campaign_id": "hwtq0"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2022-06-15T00:00:00Z",
        "bid_amount_local_micro": 3210000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": 1000000,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": true,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "ml5vs",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2022-06-03T23:47:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:47:20Z",
        "campaign_id": "hwtq0",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

POST batch/accounts/:account_id/line_items

1 回のリクエストで新しい line items をバッチ作成できるエンドポイントです。

バッチリクエスト

• 現在の最大バッチサイズは 40 件です。
• すべてのパラメータはリクエストボディで送信され、Content-Type として application/json の指定が必須です。
• バッチリクエストは 1 つのグループとしてまとめて成功または失敗し、エラーおよび成功いずれの API レスポンスにおいても、最初のリクエスト内のアイテム順序が保持されます。

バッチレスポンス

バッチ API レスポンスは順序付けされたアイテムのコレクションを返します。それ以外の点では、対応する単一アイテムのエンドポイントと構造は同一です。

バッチエラー

• リクエストレベルのエラー (例: 最大バッチサイズ超過) は、レスポンス内の errors オブジェクトに含まれます。
• アイテムレベルのエラー (例: 必須 line item パラメータの欠如) は、レスポンス内の operation_errors オブジェクトに含まれます。

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/line_items

Parameters

Name	Description
operation_type required	各アイテムに対して実行される操作の type。 Type: enum 可能な値: Create, Delete, Update
params required	line item オブジェクトのすべてのパラメータを含む JSON オブジェクト。必須および任意の line item パラメータの一覧については、こちらを参照してください。

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items

    [
      {
        "operation_type":"Create",
        "params":{
          "campaign_id":"8yn7m",
          "objective":"ENGAGEMENTS",
          "product_type":"PROMOTED_TWEETS",
          "placements":"ALL_ON_TWITTER",
          "bid_amount_local_micro":3210000,
          "entity_status":"PAUSED"
        }
      }
    ]

レスポンスの例

    {
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": null,
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": null,
          "bid_amount_local_micro": 3210000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "9cqi0",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2017-07-07T17:42:20Z",
          "ios_app_store_identifier": null,
          "updated_at": "2017-07-07T17:42:20Z",
          "campaign_id": "8yn7m",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "placements": [
              "ALL_ON_TWITTER"
            ],
            "bid_amount_local_micro": 3210000,
            "product_type": "PROMOTED_TWEETS",
            "objective": "ENGAGEMENTS",
            "entity_status": "PAUSED",
            "account_id": "18ce54d4x5t",
            "campaign_id": "8yn7m"
          },
          "operation_type": "Create"
        }
      ]
    }

​

PUT accounts/:account_id/line_items/:line_item_id

現在のアカウントに関連付けられている指定されたラインアイテムを更新します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

パラメーター

名前	説明
account_id 必須	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般に必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
line_item_id 必須	リクエストで操作する line item を参照する ID。 Type: string Example: 8v7jo
advertiser_domain 任意	この広告主のウェブサイトのドメイン (プロトコル指定を除く) 。 注: line item の placement が PUBLISHER_NETWORK に設定されている場合は必須です。 Type: string Example: x.com
advertiser_user_id 任意	PREROLL_VIEWS 広告のプロモーションを行うハンドルに対応する Twitter ユーザー ID です。特定のクライアントアプリケーションのみがこのパラメータを使用できます。 Type: string Example: 312226591
android_app_store_identifier 任意	プロモーション対象のアプリケーションの Google App Store の識別子。 注: APP_INSTALLS と APP_ENGAGEMENTS の目的では、少なくとも 1 つのアプリストア識別子 (android_app_store_identifier または ios_app_store_identifier のいずれか) を設定する必要があります。 Type: string Example: com.twitter.android
audience_expansion 任意	既にターゲティング対象となっているユーザーに類似したユーザーをターゲティングすることで、キャンペーンのリーチを拡大するために使用されます。 Type: enum Possible values: BROAD, DEFINED, EXPANDED
bid_amount_local_micro 任意	このラインアイテムに設定される入札額。指定された資金手段に紐づく通貨が使用されます。USD の場合、$5.50 は 5500000 と表されます。 注: bid_strategy が MAX または TARGET に設定されている場合は必須です。 注: 0 より大きい値のみ指定できます。 Type: long Example: 140000
bid_strategy 任意	入札戦略。 AUTO は、1 日あたりの予算とキャンペーンのフライト期間に基づいて入札を自動的に最適化します。 MAX は許容される最大入札額を設定し、objective が REACH または FOLLOWERS に設定されている場合には 利用できません。 TARGET は、指定された bid_amount_local_micro の 20% 以内に収まるように 1 日あたりの平均入札額を調整し、objective が REACH または WEBSITE_CLICKS に設定されている場合に利用できます。 注記: AUTO に設定されている場合、bid_amount_local_micro は無視されます。 注記: objective によって既定値が決まります。 Type: enum Possible values: AUTO, MAX, TARGET
categories 任意	この広告主に該当する IAB カテゴリ。詳しくは GET iab_categories を参照してください。 注記: line item の placement が PUBLISHER_NETWORK に設定されている場合に必須です。 型: string 例: IAB3-1
duration_in_days 任意	frequency_cap が適用される期間。 Type: int Possible values: 1, 7, 30
entity_status 任意	ラインアイテムのステータス。 Type: enum 有効な値: ACTIVE, PAUSED
end_time 任意	line item の配信が停止する日時を ISO 8601 形式で表したもの。 Type: string Example: 2017-10-05T00:00:00Z
frequency_cap 省略可能	1人のユーザーに配信できる広告の最大回数。 注: REACH、ENGAGEMENTS、VIDEO_VIEWS、PREROLL_VIEWS の各オブジェクティブでのみ有効です。 Type: int Example: 5
goal 任意	このラインアイテムに対して使用する最適化設定です。APP_PURCHASES オプションは APP_INSTALL で使用できます。APP_CLICKS および APP_INSTALLS オプションは APP_INSTALL と APP_ENGAGEMENTS で使用でき、サポート対象の MACT パートナー の利用が必要になる場合があります。 注記: 目的に基づいてデフォルトが設定されます。 Type: enum Possible values: APP_CLICKS, APP_INSTALLS, APP_PURCHASES, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
ios_app_store_identifier 任意	プロモーション対象アプリケーションの Apple App Store 識別子の数値部分。 Note: APP_INSTALLS および APP_ENGAGEMENTS の目的では、android_app_store_identifier または ios_app_store_identifier のいずれか、少なくとも 1 つの app store 識別子を設定する必要があります。 Type: string Example: 333903271
name 任意	このラインアイテムの名前。 Type: string Example: demo
pay_by 任意	このラインアイテムに対して課金する単位です。この設定を変更できるのは、APP_INSTALLS objective を使用するラインアイテムのみです。 注: デフォルトの pay_by は、キャンペーンの objective とラインアイテムの入札単価の単位に基づいて自動的に設定されます。 APP_INSTALLS 目的では、APP_CLICK と IMPRESSION の両方を指定できます。IMPRESSION がデフォルト値です。 LINK_CLICKS 目的では、LINK_CLICK と IMPRESSION の両方を指定できます。IMPRESSION がデフォルト値ですが、bid_strategy に対して TARGET を設定する場合はサポートされません。 SITE_VISITS 目的では、IMPRESSION の値を指定できます。 Type: enum Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
start_time 任意	ラインアイテムの配信開始時刻。ISO 8601 形式で指定します。 Type: string Example: 2017-07-05T00:00:00Z
total_budget_amount_local_micro 任意	ラインアイテムに割り当てられる合計予算額です。指定された資金手段に関連付けられている通貨が使用されます。USD の場合、$37.50 は 37500000 として表されます。 Type: long Example: 37500000
daily_budget_amount_local_micro 任意	キャンペーンに割り当てる 1 日あたりの予算額です。指定した資金源に関連付けられている通貨が使用されます。USD の場合、$5.50 は 5500000 と表されます。指定しなかった場合、キャンペーンは総予算およびキャンペーンの配信期間に基づいて均等に費消されます。親キャンペーンの budget_optimization が LINE_ITEM に設定されている場合にのみ利用できます。 注: この値は total_budget_amount_local_micro 以下である必要があります。 Type: long Example: 5500000

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000

レスポンス例

    {
      "request": {
        "params": {
          "line_item_id": "9cqi0",
          "bid_amount_local_micro": 140000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2017-07-10T00:00:00Z",
        "bid_amount_local_micro": 140000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9cqi0",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2017-07-07T17:42:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:51:36Z",
        "campaign_id": "8yn7m",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/line_items/:line_item_id

現在のアカウントに属する指定されたラインアイテムを削除します。

注記: ラインアイテムの削除は取り消しできません。その後に同じリソースを削除しようとした場合、HTTP 404 が返されます。

注記: ラインアイテムが削除されると、その子である promoted_tweets は、リクエストで with_deleted=true が指定されている場合にのみ、GET accounts/:account_id/promoted_tweets および GET accounts/:account_id/promoted_tweets/:promoted_tweet_id エンドポイントで返されます。これらの promoted_tweets 自体は実際には削除されません (レスポンスでは "deleted": false) 。削除のカスケード処理は行いません。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで原則として必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムへの参照です。 Type: string Exampple: 9f2ix

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix

Example Response

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Untitled",
        "placements": [],
        "start_time": null,
        "bid_amount_local_micro": 100000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "pay_by": "ENGAGEMENT",
        "product_type": "PROMOTED_TWEETS",
        "end_time": "2017-07-21T00:00:00Z",
        "duration_in_days": 1,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9f2ix",
        "entity_status": "ACTIVE",
        "goal": "ENGAGEMENT",
        "frequency_cap": 5,
        "categories": [],
        "currency": "USD",
        "created_at": "2017-07-14T00:01:50Z",
        "updated_at": "2017-08-09T07:41:08Z",
        "campaign_id": "90r8n",
        "creative_source": "MANUAL",
        "deleted": true
      },
      "request": {
        "params": {
          "line_item_id": "9f2ix",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

ラインアイテムのキュレーテッドカテゴリ

利用方法の詳細は、Video Views プレロール目的ガイドを参照してください。

​

GET accounts/:account_id/line_item_curated_categories

現在のアカウントに関連付けられている line item curated category の一部またはすべての詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

Name	Description
account_id required	利用対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
sort_by optional	サポートされている属性を基準に、昇順または降順でソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	リクエストに削除済みの結果を含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false
with_total_count optional	レスポンス属性 total_count を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 件に設定されている、より低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories

Example Response

    {
      "request": {
        "params": {
          "account_id": "abc1"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "by5pw",
          "curated_category_id": "7op29tp2jzeo",
          "id": "1",
          "created_at": "2018-06-29T04:19:53Z",
          "updated_at": "2018-06-29T04:19:53Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

現在のアカウントに紐づく特定の line item curated category の詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで共通して必須となるパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	リクエスト内で操作対象となる line item curated category への参照です。 Type: string Example: 43853bhii885
with_deleted optional	リクエストで削除済みの結果を含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "yav",
          "account_id": "abc1"
        }
      },
      "data": {
        "line_item_id": "by5pw",
        "curated_category_id": "7op29tp2jzeo",
        "id": "yav",
        "created_at": "2018-06-29T04:19:53Z",
        "updated_at": "2018-06-29T04:19:53Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/line_item_curated_categories

指定されたラインアイテムに curated category オブジェクトを関連付けます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストにおいて、通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
curated_category_id required	リクエストで操作対象となる curated category エンティティへの参照です。 Type: string Example: 10miy
line_item_id required	リクエストで操作対象となるラインアイテムへの参照です。 Type: string Example: 8v7jo

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "curated_category_id": "9ddrgesiap6o",
          "line_item_id": "iqwka",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T17:26:42Z",
        "deleted": false
      }
    }

​

PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

指定した line item curated category を更新します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	リクエストで操作対象となる line item curated category への参照です。 Type: string Example: 1bzq3
curated_category_id optional	リクエストで操作対象となる curated category エンティティへの参照です。 Type: string Example: 10miy
line_item_id optional	リクエストで操作対象となる line item への参照です。 Type: string Example: 8v7jo

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "8tujl1p3yn0g",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

​

DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

指定した line item curated category を削除します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	リクエストで操作対象となる line item curated category への参照です。 Type: string Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

​

ラインアイテムのプレースメント

​

GET line_items/placements

有効な placement と product_type の組み合わせを取得します。

Resource URL

https://ads-api.x.com/12/line_items/placements

Parameters

Name	Description
product_type optional	レスポンスを、指定された product_type について有効な placement のみに絞り込みます。 Type: enum Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Example Request

GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT

Example Response

    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }

​

メディアクリエイティブ

​

GET accounts/:account_id/media_creatives

現在のアカウントに関連付けられている一部またはすべてのメディアクリエイティブの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
campaign_id optional	レスポンスを、指定したキャンペーンに関連付けられているメディアクリエイティブのみに絞り込みます。 Type: string Example: 8gdx6
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
line_item_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを指定したラインアイテムに関連付けられているメディアクリエイティブのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8v7jo
media_creative_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを目的のメディアクリエイティブのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 1bzq3
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定されている、より低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "media_creative_ids": [
            "1bzq3"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8v7jo",
          "landing_url": "https://dev.x.com",
          "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
          "id": "1bzq3",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T06:00:42Z",
          "account_media_id": "10miy",
          "updated_at": "2019-01-11T20:21:26Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/media_creatives/:media_creative_id

現在のアカウントに紐づく特定のメディアクリエイティブの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

Name	Description
account_id required	利用対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータとなります。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
media_creative_id required	リクエストで操作対象となるメディアクリエイティブを示します。 Type: string Example: 43853bhii885
with_deleted optional	削除済みのものも結果に含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

POST accounts/:account_id/media_creatives

指定したラインアイテムに、account media オブジェクトを関連付けます。

このエンドポイントを使用して、インストリーム広告 (account media の creative_type が PREROLL の場合) や画像広告 (BANNER や INTERSTITIAL など) を Twitter Audience Platform 上で配信するために利用します。

注記: Account Media リソースにメディアアセットを追加するには、POST accounts/:account_id/media_library エンドポイントを使用してください。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

Name	Description
account_id required	利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
account_media_id required	リクエスト内で操作対象となる account media エンティティへの参照。 Type: string Example: 10miy
line_item_id required	リクエスト内で操作対象となるラインアイテムへの参照。 Type: string Example: 8v7jo
landing_url sometimes required	ユーザーを誘導するウェブサイトの URL。このパラメータは TAP 画像 (「display creatives」) でのみ使用してください。preroll アセットで使用した場合、この値は無視されます。preroll アセットに URL を関連付けるには、POST accounts/:account_id/preroll_call_to_actions エンドポイントを使用してください。 注記: ラインアイテムの objective が WEBSITE_CLICKS に設定されている場合に必須です。 Type: string Example: https://blog.x.com/

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "account_media_id": "10miy",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/media_creatives/:media_creative_id

現在のアカウントに属する指定の media creative を削除します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

Name	Description
account_id required	利用対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
media_creative_id required	このリクエストで操作する media creative への参照です。 Type: string Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2021-04-16T21:02:55Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      }
    }

​

プロモーション対象アカウント

​

GET accounts/:account_id/promoted_accounts

現在のアカウント配下の 1 つ以上のラインアイテムに紐づく、一部またはすべてのプロモーションアカウントの詳細を取得します。

レスポンス内の user_id で特定されるユーザーアカウントのユーザーデータを取得するには、GET users/lookup を使用してください。

指定したいずれのラインアイテムもプロモーションアカウントを含むように設定されていない場合、HTTP 400 が返されます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

Name	Description
account_id required	利用されるアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定したアカウントは認証済みユーザーに紐づいている必要があります。 Type: string Example: 18ce54d4x5t
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
line_item_ids optional	コンマ区切りの識別子リストを指定して、レスポンスを指定したラインアイテムに紐づくプロモーションアカウントのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 9bpb2
promoted_account_ids optional	コンマ区切りの識別子リストを指定して、レスポンスを目的のプロモーションアカウントのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 19pl2
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストではレート制限が低くなり、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_ids": [
            "19pl2"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "9bpb2",
          "user_id": "756201191646691328",
          "id": "19pl2",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T05:54:13Z",
          "updated_at": "2017-07-05T05:54:13Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/promoted_accounts/:promoted_account_id

現在のアカウント配下のラインアイテムに関連付けられたアカウントを指す特定の参照を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

Name	Description
account_id required	対象となるアカウントを識別する id です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、通常は必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
promoted_account_id required	リクエストで操作対象となるプロモーション対象アカウントへの参照です。 Type: string Example: 19pl2
with_deleted optional	削除済みの結果も含めます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

​

POST accounts/:account_id/promoted_accounts

指定されたラインアイテムにアカウント (user_id) を関連付けます。

指定されたラインアイテムが Promoted Accounts と関連付けるように構成されていない場合、HTTP 400 INCOMPATIBLE_LINE_ITEM エラーが返されます。指定されたユーザーがプロモーション対象外の場合、HTTP 400 が返され、いずれのユーザーもプロモーションは行われません。指定されたユーザーがすでにプロモーション済みである場合、そのリクエストは無視されます。

Promoted Accounts の詳細については、campaign management ページを参照してください。

注記: Promoted Accounts エンティティを更新 (PUT) することはできません。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

Name	Description
account_id required	対象のアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエスト内で操作対象となるラインアイテムへの参照です。 Type: string Example: 9bpb2
user_id required	リクエスト内で操作対象となるユーザーへの参照です。スクリーンネームに対応するユーザー ID を取得するには、GET users/lookup を使用してください。 Type: long Example: 756201191646691328

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      },
      "request": {
        "params": {
          "user_id": "756201191646691328",
          "line_item_id": "9bpb2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

指定されたラインアイテムからアカウントの関連付けを解除します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
promoted_account_id required	ラインアイテムに関連付けられている Promoted Account のインスタンスを指す識別子です。 Type: string Example: 19pl2

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-08-23T18:53:15Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

プロモツイート

​

GET accounts/:account_id/promoted_tweets

現在のアカウントのラインアイテムに関連付けられたツイート参照を取得します。

ツイートオブジェクトを取得するには、GET accounts/:account_id/tweets エンドポイントを使用してください。各 promoted_tweets オブジェクトの tweet_id の値を使用します。

注記: 親のラインアイテムが削除されている場合、リクエストで with_deleted=true が指定されているときにのみ promoted_tweets が返されます。これらの promoted_tweets 自体は削除されていません (レスポンス中の "deleted": false を参照) 。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

Name	Description
account_id required	利用対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証されたユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
line_item_ids optional	識別子のカンマ区切りリストを指定して、特定のラインアイテムに関連付けられたツイートのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 96uzp
promoted_tweet_ids optional	識別子のカンマ区切りリストを指定して、特定のプロモーションツイートのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 1efwlo
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をリクエストに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 注記: このパラメータと cursor は排他的です。 注記: total_count を含むリクエストは、現在 15 分あたり 200 に設定されているより低いレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_ids": [
            "1efwlo"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "96uzp",
          "id": "1efwlo",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-29T05:06:57Z",
          "updated_at": "2017-06-29T05:08:46Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "880290790664060928",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/promoted_tweets/:promoted_tweet_id

現在のアカウント配下のラインアイテムに紐づく特定のプロモツイート (promoted Tweet) への参照を取得します。

注: 親ラインアイテムが削除されている場合、リクエストで with_deleted=true が指定されているときにのみ、promoted_tweets が返されます。これらの promoted_tweets 自体は実際には削除されていません (レスポンスでは "deleted": false となります) 。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
promoted_tweet_id required	リクエスト内で操作対象となるプロモツイート (promoted Tweet) を参照する id です。 Type: string Example: 1efwlo
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_id": "1efwlo",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "96uzp",
        "id": "1efwlo",
        "entity_status": "ACTIVE",
        "created_at": "2017-06-29T05:06:57Z",
        "updated_at": "2017-06-29T05:08:46Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "880290790664060928",
        "deleted": false
      }
    }

​

POST accounts/:account_id/promoted_tweets

指定されたラインアイテムに 1 つ以上のツイートを関連付けます。キャンペーンの目的によっては、すべてのツイートがプロモーション対象として適切とは限りません。詳しくは Objective-based Campaigns を参照してください。

PROMOTED_ACCOUNT プロダクト type を使用する場合、ツイートを line_item に関連付けると、標準の PROMOTED_ACCOUNT プレースメントに加えて、モバイルのタイムライン上でのプレースメントが追加されます。

注: プロモーション対象ツイートエンティティを更新 (PUT) することはできません。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムを参照します。 Type: string Example: 8v7jo
tweet_ids required	特定のツイートに対応する識別子のカンマ区切りリストです。最大 50 個の ID を指定できます。 Type: long Example: 822333526255120384

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384

Example Response

    {
      "data": [
        {
          "line_item_id": "8v7jo",
          "id": "1e8i2k",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-24T04:21:36Z",
          "updated_at": "2017-06-24T04:21:36Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "822333526255120384",
          "deleted": false
        }
      ],
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "tweet_ids": [
            822333526255120384
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "total_count": 1
    }

​

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

指定されたラインアイテムからツイートの関連付けを解除します。

注: 削除された promoted_tweets エンティティは、ads.x.com の UI 上で「Paused」と表示されます。同様に、UI から「一時停止」した場合も、そのツイートはラインアイテムとの関連付けが解除されます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id

Parameters

Name	Description
account_id required	利用しているアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
promoted_tweet_id required	ラインアイテムに関連付けられた Promoted Tweet のインスタンスを指す識別子です。これは、対象のツイートの tweet_id ではなく、GET accounts/:account_id/promoted_tweets に対するレスポンス項目の id フィールドから取得されます。リソースのパス内で指定します。 Type: string Example: 1gp8a5

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5

Example Response

    {
      "data": {
        "line_item_id": "9pl99",
        "id": "1gp8a5",
        "entity_status": "ACTIVE",
        "created_at": "2017-08-17T17:02:21Z",
        "updated_at": "2017-08-18T06:43:48Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "844796297743757315",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_tweet_id": "1gp8a5",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

プロモーション対象ユーザー

​

GET accounts/:account_id/promotable_users

現在のアカウントに関連付けられている一部またはすべてのプロモーション可能ユーザーの詳細を取得します。

プロモーション可能ユーザーのtypeは FULL または RETWEETS_ONLY のいずれかです。これは、そのアカウントによってプロモーションできるコンテンツの種類を制御します。広告主は、他のユーザーのコンテンツをプロモーションする権限を取得し、そのユーザーを RETWEETS_ONLY のプロモーション可能ユーザーとして自分のアカウントに追加してもらうために X に連絡する必要があります。

権限が正しく設定されていれば、プロモーション用プロダクトのエンドポイントに対して、プロモーションしたいツイートの Tweet ID を直接参照するリクエストを行うことができます。公開済みツイートをプロモーションするには POST accounts/:account_id/promoted-tweets エンドポイントを利用し、他の X 広告アカウントの予約済みツイートをプロモーションするには POST accounts/:account_id/scheduled-promoted-tweets エンドポイントを利用できます。

対象ツイートをリツイートする必要はありません。この方法でツイートをプロモーションすると、返される tweet_id は、指定した Tweet ID とは異なる値になります。内部的には、そのツイートは nullcast されたツイートとしてリツイートされ、その後プロモーションされます。返される tweet_id は、この新しいツイートに対応しています。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーと関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	個々のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
promotable_user_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを希望するプロモーション可能ユーザーのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: l310s
sort_by optional	サポートされている属性を基準に、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は同時には使用できません。 Note: total_count を含むリクエストはレート制限がより低くなり、現在は 15 分あたり 200 件に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_ids": [
            "l310s"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "user_id": "756201191646691328",
          "id": "l310s",
          "created_at": "2016-07-21T22:42:09Z",
          "updated_at": "2016-07-21T22:42:09Z",
          "deleted": false,
          "promotable_user_type": "FULL"
        }
      ]
    }

​

GET accounts/:account_id/promotable_users/:promotable_user_id

現在のアカウントに関連付けられている特定のプロモーション対象ユーザーを取得します。

プロモーション対象ユーザーの type は FULL または RETWEETS_ONLY のいずれかです。これは、そのアカウントでプロモーションできるコンテンツの種類を制御します。

広告主は、他のユーザーのコンテンツをプロモーションするための権限を取得する必要があります。権限が正しく設定されていれば、プロモーションしたいツイートの Tweet ID を直接参照するプロモーションプロダクトのエンドポイントに対してリクエストを行うことができます。

対象のツイートをリツイートする必要はありません。この方法でツイートをプロモーションする場合、返される tweet_id は指定した Tweet ID とは異なります。内部的には、そのツイートは nullcast されたツイートとしてリツイートされ、その後プロモーションされます。返される tweet_id はこの新しいツイートに対応します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
promotable_user_id optional	リクエスト内で操作対象となるプロモーション対象ユーザーへの参照です。 Type: string Example: l310s
with_deleted optional	リクエストの結果に削除済みのものを含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_id": "l310s",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "user_id": "2417045708",
        "id": "l310s",
        "created_at": "2017-03-10T17:51:24Z",
        "updated_at": "2017-03-10T17:51:24Z",
        "deleted": false,
        "promotable_user_type": "RETWEETS_ONLY"
      }
    }

​

パブリッシャー

​

GET publishers

コンテンツカテゴリに属するパブリッシャーの詳細一覧を取得します

詳細については、Video Views Preroll Objective Guide を参照してください

Resource URL

https://ads-api.x.com/12/publishers

Parameters

リクエストパラメーターはありません

Example Request

GET https://ads-api.x.com/12/publishers

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "PeoplesSports",
          "user_id": "1353868435021721602",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "NewYork_Jack",
          "user_id": "1331177123436851206",
          "monetization_restricted": true,
          "content_category_ids": [
            "sk"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "twispatv",
          "user_id": "1331165719128461314",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "LAThieves",
          "user_id": "1316808678897455105",
          "monetization_restricted": true,
          "content_category_ids": [
            "s0"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Quicktake_EE",
          "user_id": "1305900477427724290",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "BR"
          ],
          "promotion_eligible_country_codes": [
            "BR"
          ],
          "username": "eufloribella",
          "user_id": "1300812459054436354",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "EG"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "Egypt2021EN",
          "user_id": "1296077573399678977",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "ClubShayShay",
          "user_id": "1283068366706454529",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "hiaahsanshow",
          "user_id": "1253421442143641601",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "TH"
          ],
          "promotion_eligible_country_codes": [
            "TH"
          ],
          "username": "HoneKrasae",
          "user_id": "1240684293719904256",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Sportskind",
          "user_id": "1232708694418300930",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "almeerathShow",
          "user_id": "1229410512762437633",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "SeeYourVoiceFOX",
          "user_id": "1225490734653947904",
          "monetization_restricted": true,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "AUProSports",
          "user_id": "1219303449768185859",
          "monetization_restricted": false,
          "content_category_ids": [
            "se"
          ]
        }
      ]
    }

​

推奨

​

GET accounts/:account_id/recommendations

ステータス: クローズドベータ

この広告アカウントに関連付けられたキャンペーンのレコメンデーションを取得します。現在、1つのファンディングインストゥルメントあたり取得できるレコメンデーションは1件までです。

リソース URL

https://ads-api.x.com/5/accounts/:account_id/recommendations

パラメータ

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほぼすべての Advertiser API リクエストで一般的に必須となるパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t

リクエスト例

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations

レスポンス例

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "PENDING",
        "message": "Recommendation for testing",
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

​

GET accounts/:account_id/recommendations/:recommendation_id

Status: クローズドベータ

この広告アカウントに関連付けられた特定のキャンペーンレコメンデーションを取得します。

キャンペーンレコメンデーションには、オブジェクトツリーとして表現されたキャンペーン構造に対して提案される変更内容一式が含まれます。レスポンスツリーは Batch API エンドポイントと組み合わせて使用されることを想定していますが、必要に応じて単一の更新エンドポイント (POST の Create、PUT の Update、DELETE の Delete) にマッピングすることもできます。

Resource URL

https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くほとんどすべての Advertiser API リクエストで一般的に必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
recommendation_id required	リクエストで操作対象となるレコメンデーション ID への参照です。 Type: string Example: 62ce8zza1q0w

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w

Example Response

{
    "request": {
      "params": {
        "recommendation_id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t"
      }
    },
    "data_type": "recommendations",
      "data": {
      "changes": [
        {
          "entity_type": "campaigns",
          "params": {
            "start_time": "2016-11-08T22:00:00Z",
            "daily_budget_amount_local_micro": 2200000,
            "end_time": "2016-11-16T07:59:00Z",
            "total_budget_amount_local_micro": 12000000,
            "id": "64m0d"
          },
          "operation_type": "Update",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "レコメンデーション用キャンペーン",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL"
              },
              "operation_type": "Update",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "選挙結果",
                    "targeting_value": "選挙結果",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "男性",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "サンフランシスコ・オークランド・サンノゼ CA, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "パートナーオーディエンスターゲティング",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "AGE_21_TO_34",
                    "targeting_value": "AGE_21_TO_34",
                    "targeting_type": "AGE"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "討論会",
                    "targeting_value": "討論会",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "60004, IL, US",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6n"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftn"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                }
              ]
            }
          ]
        }
      ],
      "funding_instrument_id": "gpvzb",
      "id": "62ce8zza1q0w",
      "account_id": "18ce54d4x5t",
      "status": "PENDING",
      "message": "テスト用レコメンデーション",
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

スケジュール済みプロモツイート

​

GET accounts/:account_id/scheduled_promoted_tweets

現在のアカウントに関連付けられている一部またはすべての予約済みプロモツイートの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するための cursor を指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
line_item_ids optional	カンマ区切りの識別子リストを指定することで、特定のラインアイテムに関連付けられた予約済みツイートのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8xdpe
scheduled_promoted_tweet_ids optional	カンマ区切りの識別子リストを指定することで、特定の予約済みプロモツイートのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 1xboq
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 回に設定されている、より厳しいレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq

Example Response

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_ids": [
            "1xboq"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8xdpe",
          "id": "1xboq",
          "created_at": "2017-06-01T19:53:32Z",
          "updated_at": "2017-06-01T20:00:06Z",
          "scheduled_tweet_id": "870366669373194240",
          "tweet_id": "870369382207070208",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

現在のアカウントに関連付けられている特定の予約済みプロモーションツイートを取得します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	リクエスト内で操作対象となる予約済みプロモーションツイートを参照する識別子です。 Type: string Example: 1xboq
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq

レスポンス例

    {
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xboq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xboq",
        "created_at": "2017-06-01T19:53:32Z",
        "updated_at": "2017-06-01T20:00:06Z",
        "scheduled_tweet_id": "870366669373194240",
        "tweet_id": "870369382207070208",
        "deleted": false
      }
    }

​

POST accounts/:account_id/scheduled_promoted_tweets

指定したラインアイテムに予約済みツイートを関連付けます。

Note: 予約済みプロモツイートエンティティを更新 (PUT) することはできません。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets

Parameters

Name	Description
account_id required	利用しているアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常、必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムへの参照です。 Type: string Example: 8xdpe
scheduled_tweet_id required	リクエストで操作対象となる予約済みツイートへの参照です。 Type: long Example: 870358555227860992

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992

Example Response

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-08T07:25:26Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": false
      },
      "request": {
        "params": {
          "line_item_id": "8xdpe",
          "scheduled_tweet_id": 870358555227860992,
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

指定されたラインアイテムから予約済みツイートの紐付けを解除します。

注: scheduled_promoted_tweets は、予約済みツイートの scheduled_at 時刻「前」にのみ削除できます。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

パラメーター

Name	Description
account_id required	利用対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、通常必須パラメーターとなります。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	リクエストで操作対象となる予約済みプロモーションツイートを参照するための値です。これは GET accounts/:account_id/scheduled_promoted_tweets のレスポンスオブジェクト内に含まれる id 属性です。 Type: string Example: 1xtfl

リクエスト例

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl

レスポンス例

    {
      "data": {
        "line_item_id": "8xdpe",
        "id": "1xtfl",
        "created_at": "2017-06-08T07:25:26Z",
        "updated_at": "2017-06-15T05:14:12Z",
        "scheduled_tweet_id": "870358555227860992",
        "tweet_id": null,
        "deleted": true
      },
      "request": {
        "params": {
          "scheduled_promoted_tweet_id": "1xtfl",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

ターゲティング条件

​

GET accounts/:account_id/targeting_criteria

現在のアカウント配下のラインアイテムに関連付けられているターゲティング条件の詳細を、一部またはすべて取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストにおいて一般的に必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_ids required	カンマ区切りの識別子のリストを指定して、レスポンスを指定したラインアイテム配下のターゲティング条件のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 8u94t
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
lang optional	ISO-639-1 の言語コードです。指定すると、ローカライズされた名前が利用可能なオブジェクトについては、レスポンス内に追加で localized_name 属性が返されます。 Type: string Example: fr
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
targeting_criterion_ids optional	カンマ区切りの識別子のリストを指定して、レスポンスを必要なターゲティング条件のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: dpl3a6
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	レスポンス属性 total_count を含めます。 注: このパラメータと cursor は同時には使用できません。 注: total_count を含むリクエストはレート制限がより厳しくなり、現在は 15 分あたり 200 に設定されています。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "8u94t"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8u94t",
          "name": "カスタムオーディエンスターゲティング",
          "id": "dpl3a6",
          "operator_type": "EQ",
          "created_at": "2017-05-26T03:29:35Z",
          "targeting_value": "249yj",
          "updated_at": "2017-05-26T03:29:35Z",
          "deleted": false,
          "targeting_type": "CUSTOM_AUDIENCE"
        }
      ]
    }

​

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

現在のアカウントに関連付けられている特定のターゲティング条件を取得します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id

パラメーター

Name	説明
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須のパラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
targeting_criterion_id required	リクエストで操作対象となるターゲティング条件を指す参照です。 Type: string Example: eijd4y
lang optional	ISO-639-1 言語コードです。指定された場合、ローカライズされた名前が利用可能なオブジェクトについては、レスポンスに追加の localized_name 属性が返されます。 Type: string Example: fr
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y

レスポンス例

    {
      "request": {
        "params": {
          "targeting_criterion_id": "eijd4y",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "619jl",
        "name": "🤖",
        "id": "eijd4y",
        "created_at": "2017-07-06T16:51:04Z",
        "targeting_value": "🤖",
        "updated_at": "2017-07-06T16:51:04Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      }
    }

​

POST accounts/:account_id/targeting_criteria

特定のターゲティング type に対応する targeting_value を確認するには、Targeting Options ページを参照してください。常に最新のターゲティング type の値を利用できるよう、すべてのデータを毎週更新することを推奨します。X では値や利用可能なターゲティング条件を随時変更します。多くは頻繁には変更されませんが、なかには頻繁に変更されるものもあります。これらの値が変更されないことは保証されません。

BROAD_KEYWORD、EXACT_KEYWORD、PHRASE_KEYWORD、UNORDERED_KEYWORD の各ターゲティング type を、targeting_value で指定したキーワードとともに使用します。operator_type リクエストパラメータを NE に設定することで、キーワードを除外できます。各 type の詳細な説明については targeting keyword types を参照してください。

Note: 1 つのラインアイテムにつき、ターゲットにできる AGE バケットは 1 つだけです。

Note: Custom Audience をターゲティングするには、そのオーディエンスがターゲット可能である必要があります。つまり、targerable が true で なければなりません。

Note: ターゲティング type として TV_SHOW を使用する場合、TV_SHOW ターゲティングを設定する前に、そのラインアイテムに少なくとも 1 つの LOCATION ターゲティング条件が存在している必要があります。また、すべての LOCATION はターゲットとする TV_SHOW と同じロケール内でなければなりません。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria

パラメータ

Name	Description
account_id required	利用するアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定したアカウントは、認証されたユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムの参照です。 Type: string Example: 69ob
operator_type required	ターゲティング条件が持つべき関係を指定します。たとえば、キーワードを除外するには operator_type=NE を使用します。 Type: enum Possible values: EQ, NE, GTE, LT
targeting_type required	このラインアイテムに適用されるターゲティングの type です。 キーワードベースではない取り得る値には、AGE、DEVICE、EVENT、CAMPAIGN_ENGAGEMENT、CAMPAIGN_ENGAGEMENT_LOOKALIKE、CONVERSATION、ENGAGEMENT_TYPE、FOLLOWERS_OF_USER、GENDER、INTEREST、LANGUAGE、LIVE_TV_EVENT、LOCATION、NETWORK_ACTIVATION_DURATION、NETWORK_OPERATOR、PLATFORM、PLATFORM_VERSION、SIMILAR_TO_FOLLOWERS_OF_USER、TV_SHOW、USER_ENGAGEMENT、USER_ENGAGEMENT_LOOKALIKE、WIFI_ONLY などがあります。 Note: 1 つのラインアイテムにつき、ターゲットにできる AGE バケットは 1 つだけです。 キーワードベースの取り得る値には、BROAD_KEYWORD、EXACT_KEYWORD、PHRASE_KEYWORD、UNORDERED_KEYWORD があります。 Custom Audience 向けの取り得る値には、CUSTOM_AUDIENCE、CUSTOM_AUDIENCE_EXPANDED があります。 インストール済み App ストアカテゴリ向けの取り得る値には、APP_STORE_CATEGORY、APP_STORE_CATEGORY_LOOKALIKE があります。 Twitter Audience Platform (TAP) の App 除外向けの取り得る値には、APP_LIST があります (operator_type=NE と組み合わせてのみ使用可能)。
targeting_value required	選択した targeting_type に応じて、このターゲティングを適用する対象となるユーザー、興味関心、ロケーション、イベント、プラットフォーム、プラットフォームバージョン、デバイス、キーワードまたはフレーズ、性別、Custom Audience、App ストアカテゴリ、または App リスト除外を指定します。 Type: string Example: 174958347

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology

レスポンス例

    {
      "data": {
        "line_item_id": "619jl",
        "name": "technology",
        "id": "fbyjlr",
        "created_at": "2017-09-06T07:31:21Z",
        "targeting_value": "technology",
        "updated_at": "2017-09-06T07:31:21Z",
        "deleted": false,
        "targeting_type": "BROAD_KEYWORD"
      },
      "request": {
        "params": {
          "line_item_id": "619jl",
          "targeting_type": "BROAD_KEYWORD",
          "targeting_value": "technology",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

POST batch/accounts/:account_id/targeting_criteria

1 回のリクエストで新しいターゲティング条件をバッチ作成できます。

バッチリクエスト

• 現在の最大バッチサイズは 500 です。
• すべてのパラメータはリクエストボディで送信され、Content-Type として application/json が必須です。
• バッチリクエストはグループとして全体で成功または失敗し、エラーおよび成功の両方の API レスポンスで、最初のリクエストにおける各項目の順序が保持されます。

バッチレスポンス

バッチ API レスポンスは順序付きの項目コレクションを返します。構造は、それぞれに対応する単一項目エンドポイントと同一です。

バッチエラー

• リクエストレベルのエラー (例: 最大バッチサイズ超過) はレスポンス内の errors オブジェクトとして返されます。
• 項目レベルのエラー (例: 必須ターゲティング条件パラメータの欠如) はレスポンス内の operation_errors オブジェクトとして返されます。

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria

Parameters

Name	Description
operation_type required	各項目に対して実行する操作の種別です。 Type: enum 可能な値: Create, Delete
params required	ターゲティング条件オブジェクト用のすべてのパラメータを含む JSON オブジェクトです。必須および任意のターゲティング条件パラメータの一覧はこちらを参照してください。 さらに、このエンドポイントは特定の targeting_type の値と組み合わせて動作する operator_type パラメータをサポートします。このパラメータの可能な値は、等しいことを表す EQ、以上を表す GTE、未満を表す LT、等しくないことを表す NE です。

Example Request

POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria

    [
      {
        "operation_type":"Create",
        "params":{
          "line_item_id":"6f9an",
          "targeting_type":"LOCATION",
          "targeting_value":"5122804691e5fecc"
        }
      },
      {
        "operation_type":"Delete",
        "params":{
          "targeting_criterion_id":"al2rua"
        }
      }
    ]

レスポンス例

    {
      "data_type": "targeting_criterion",
      "data": [
        {
          "line_item_id": "6f9an",
          "name": "San Francisco-Oakland-San Jose CA, US",
          "id": "al7vt2",
          "location_type": "CITY",
          "operator_type": "EQ",
          "created_at": "2016-11-11T22:59:50Z",
          "targeting_value": "5122804691e5fecc",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": false,
          "targeting_type": "LOCATION"
        },
        {
          "line_item_id": "6keuo",
          "name": "accounts",
          "id": "al2rua",
          "operator_type": "EQ",
          "created_at": "2016-11-11T17:50:19Z",
          "targeting_value": "accounts",
          "updated_at": "2016-11-11T22:59:50Z",
          "deleted": true,
          "targeting_type": "BROAD_KEYWORD"
        }
      ],
      "request": [
        {
          "params": {
            "line_item_id": "6f9an",
            "targeting_type": "LOCATION",
            "targeting_value": "5122804691e5fecc",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        },
        {
          "params": {
            "targeting_criterion_id": "al2rua",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Delete"
        }
      ]
    }

​

DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id

現在のアカウントに属する指定されたターゲティング条件を削除します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
targeting_criterion_id required	リクエスト内で操作するターゲティング条件を参照する ID。 Type: string Example: dpl3a6

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6

Example Response

    {
      "data": {
        "line_item_id": "8u94t",
        "name": "Custom audience targeting",
        "id": "dpl3a6",
        "created_at": "2017-05-26T03:29:35Z",
        "targeting_value": "249yj",
        "updated_at": "2017-08-30T18:38:58Z",
        "deleted": true,
        "targeting_type": "CUSTOM_AUDIENCE"
      },
      "request": {
        "params": {
          "targeting_criterion_id": "dpl3a6",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

ターゲティングオプション

• App Store カテゴリー
• 会話
• デバイス
• イベント
• 興味関心
• 言語
• ロケーション
• 通信事業者
• プラットフォームバージョン
• プラットフォーム
• テレビ市場
• テレビ番組

​

GET targeting_criteria/app_store_categories

Promoted Products 向けに利用可能な、アプリストアカテゴリに基づくターゲティング条件を取得します。アプリストアカテゴリは iOS App Store と Google Play ストアでのみ利用可能です。

インストール済みアプリカテゴリターゲティングを使用すると、ユーザーがインストールしている、または興味を示したアプリのカテゴリに基づいてユーザーをターゲティングできます。

Resource URL

https://ads-api.x.com/12/targeting_criteria/app_store_categories

Parameters

Name	Description
q optional	ターゲティング条件を絞り込む任意指定のクエリです。このパラメータを省略すると、すべてを取得します。 Type: string Example: music
os_type optional	結果を特定のアプリストアで絞り込みます。 Type: enum Possible values: ANDROID, IOS

Example Request

GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS

Example Response

    {
      "data": [
        {
          "name": "Games: Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "Music",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "music",
          "os_type": "IOS"
        }
      }
    }

​

GET targeting_criteria/conversations

Promoted Products 向けに利用可能な会話ベースのターゲティング条件を取得します。

Resource URL

https://ads-api.x.com/12/targeting_criteria/conversations

Parameters

Name	Description
conversation_type optional	特定の会話タイプにスコープを絞るための任意のクエリパラメータです。 Type: enum 指定可能な値: ACTORS, ATHLETES, BOOK_GENRES, BOOKS, BRAND_CATEGORIES, BRANDS, CELEBRITIES, COACHES, DIGITAL_CREATORS, ENTERTAINMENT_BRANDS, ENTERTAINMENT_PERSONALITIES, FICTIONAL_CHARACTERS, JOURNALISTS, LIFESTYLES, MOVIE_GENRES, MOVIES, MUSIC_GENRES, MUSICIANS, NEWS_STORIES, NEWS, PERSONS, PLACES, PODCASTS, POLITICAL_AFFILIATIONS, POLITICIANS, PRODUCTS, RADIO_STATIONS, SPORTS_LEAGUES, SPORTS_PERSONALITIES, SPORTS_TEAMS, SPORTS, TRENDS, TV_SHOWS, VIDEO_GAME_PLATFORMS, VIDEO_GAME_PUBLISHERS, VIDEO_GAMES
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2

Example Response

    {
      "request": {
        "params": {
          "count": 2
        }
      },
      "next_cursor": "1f7m7",
      "data": [
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a1",
          "name": "NFL",
          "conversation_type": "SPORTS"
        },
        {
          "targeting_type": "CONVERSATION",
          "targeting_value": "a2",
          "name": "NBA",
          "conversation_type": "SPORTS"
        }
      ]
    }

​

GET targeting_criteria/devices

プロモーションプロダクト向けに利用可能なデバイスベースのターゲティング条件を取得します。デバイスターゲティングはプロモツイートで利用できます。

リソース URL

https://ads-api.x.com/12/targeting_criteria/devices

パラメータ

Name	Description
count optional	1 回のリクエストで取得するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
q optional	ターゲティング条件を絞り込むための任意のクエリです。すべてを取得する場合は、このパラメータを省略します。 Type: string Example: apple

リクエスト例

GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone

レスポンス例

    {
      "data": [
        {
          "name": "iPhone 3GS",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1q",
          "targeting_type": "DEVICE"
        },
        {
          "name": "iPhone 4",
          "manufacturer": "Apple",
          "os_type": "iOS",
          "targeting_value": "1r",
          "targeting_type": "DEVICE"
        }
      ],
      "request": {
        "params": {
          "q": "iphone",
          "count": 2
        }
      }
    }

​

GET targeting_criteria/events

Promoted Products 向けに利用可能なイベントベースのターゲティング条件を取得します。1 つのラインアイテムにつき、ターゲットにできるイベントは 1 件のみです。

注記: イベントはしばしば複数のタイムゾーンにまたがって発生するため、異なるタイムゾーン越しにイベント時刻を扱う際に複雑さが生じます。これを簡素化するため、このエンドポイントで扱うすべてのイベントの start_time および end_time の値は、イベントのロケールやタイムゾーンに関係なく UTC±00:00 で表現されます。イベントの start_time および end_time の値をクエリしたり操作したりする際には、この設計を念頭に置いてください。たとえば、米国の独立記念日 (Independence Day) は、UTC±00:00 において start_time=2017-07-04T00:00:00Z および end_time=2017-07-05T00:00:00Z として表現されるため、この祝日が米国内の複数タイムゾーンにまたがって存在するという問題を回避できます。

Resource URL

https://ads-api.x.com/12/targeting_criteria/events

Parameters

Name	Description
event_types required	特定のイベント type に絞り込むためのオプションのクエリです。 Type: enum Possible values: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
country_codes optional	2 文字の ISO 国コードを使用して、ターゲティング条件検索の対象を特定の国に絞り込むためのオプションのクエリです。このパラメータが指定されていない場合、すべてのイベントが返されます。 Type: string
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
end_time optional	キャンペーンが終了する時刻を、ISO 8601 形式で指定します。 Type: string Example: 2017-10-05T00:00:00Z
start_time optional	ラインアイテムの配信開始時刻を、ISO 8601 形式で指定します。 注記: 省略時は現在時刻がデフォルトとして使用されます。 Type: string Example: 2017-07-05T00:00:00Z

Example Request

GET https://ads-api.x.com/12/targeting_criteria/events?count=1

Example Response

    {
      "request": {
        "params": {
          "count": 1
        }
      },
      "data_type": "events",
      "data": [
        {
          "reach": {
            "total_reach": null
          },
          "name": "New Year's",
          "start_time": "2017-12-31T00:00:00Z",
          "top_users": [],
          "top_tweets": [],
          "top_hashtags": [],
          "gender_breakdown_percentage": {},
          "end_time": "2018-01-02T00:00:00Z",
          "country_code": null,
          "device_breakdown_percentage": {},
          "targeting_value": "1ex",
          "is_global": true,
          "event_type": "HOLIDAY",
          "country_breakdown_percentage": {}
        }
      ],
      "next_cursor": "uww0"
    }

​

GET targeting_criteria/interests

プロモーションプロダクト向けに利用可能な、興味・関心ベースのターゲティング条件を取得します。インタレストは頻繁には変更されませんが、このリストは少なくとも週に一度は更新することを推奨します。

Resource URL

https://ads-api.x.com/12/targeting_criteria/interests

Parameters

Name	Description
count optional	個別のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	ターゲティング条件の範囲を絞り込むための任意のクエリです。すべてを取得する場合は、このパラメータを省略してください。 Type: string Example: books

Example Request

GET https://ads-api.x.com/12/targeting_criteria/interests?q=books

Example Response

    {
      "data": [
        {
          "name": "Books and literature/Biographies and memoirs",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "books",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

ターゲティングに利用可能な言語を取得します。

Resource URL

https://ads-api.x.com/12/targeting_criteria/languages

Parameters

Name	Description
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	ターゲティング条件を絞り込むための任意のクエリです。すべてを取得する場合は、このパラメータを省略してください。 Type: string Example: english

Example Request

GET https://ads-api.x.com/12/targeting_criteria/languages?q=english

Example Response

    {
      "data": [
        {
          "name": "English",
          "targeting_type": "LANGUAGE",
          "targeting_value": "en"
        }
      ],
      "request": {
        "params": {
          "q": "english"
        }
      },
      "next_cursor": null
    }

​

GET targeting_criteria/locations

Promoted Products 向けに利用可能な、位置情報に基づくターゲティング条件を取得します。ジオターゲティングは、国レベル、州/地域レベル、市区町村レベル、郵便番号レベルで、Promoted Accounts と Promoted Tweets に対して利用できます。郵便番号レベルで分析情報を取得する場合は、郵便番号ターゲティングを使用する必要があります。

注: San Francisco や New York など、特定のターゲット可能な都市を取得するには、location_type リクエストパラメータと併せて CITIES enum を使用してください。

指定市場エリア (DMA: Designated Market Areas) をターゲットにするには、METROS enum を使用してください。

Resource URL

https://ads-api.x.com/12/targeting_criteria/locations

Parameters

Name	Description
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
country_code optional	2 文字の ISO 国コードで、ターゲティング条件の検索対象を特定の国に絞り込むための任意パラメータです。すべての国を対象とする結果を取得するには、このパラメータを省略します。 Type: string Example: JP
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
location_type optional	特定の種類のロケーションで結果を絞り込みます。COUNTRIES よりも細かいターゲティングは、すべてのロケーションで利用できるとは限りません。 Type: enum Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q optional	ターゲティング条件の検索対象を絞り込むための任意パラメータです。すべての結果を取得するには、このパラメータを省略します。 Type: string Example: New York

Example Request

GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles

Example Response

    {
      "data": [
        {
          "name": "Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "3b77caf94bfc81fe",
          "targeting_type": "LOCATION"
        },
        {
          "name": "East Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "67571a7baaa5906b",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Lake Los Angeles, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "ea9bfbd43c93400f",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "a2de7c70b82b0ca0",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Altos, Monterey-Salinas CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "6a4364ea6f987c10",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Banos, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "b1b6fc646de75904",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Alamitos, Los Angeles CA, CA, USA",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "0799ff0a3c1006e9",
          "targeting_type": "LOCATION"
        },
        {
          "name": "Los Angeles, US",
          "country_code": "US",
          "location_type": "CITIES",
          "targeting_value": "019940ae78c7b3bc",
          "targeting_type": "LOCATION"
        }
      ],
      "request": {
        "params": {
          "location_type": "CITIES",
          "q": "los angeles"
        }
      },
      "next_cursor": null
    }

​

GET targeting_criteria/network_operators

Promoted Products 向けに利用可能な、ネットワークオペレーター (通信事業者) ベースのターゲティング条件を取得できます。

このエンドポイントでは、AT&T、Verizon、Sprint、T-Mobile など、複数の国におけるターゲティング可能な通信キャリアを検索できます。

Resource URL

https://ads-api.x.com/12/targeting_criteria/network_operators

Parameters

Name	Description
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
country_code optional	2 文字の ISO 国コードを使用して、特定の国にターゲティング条件の検索範囲を絞り込むためのオプションのクエリです。このパラメーターを指定しない場合、米国のパートナーオーディエンスのみが返されます。 Type: string Default: US
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細については Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	ターゲティング条件の検索範囲を絞り込むためのオプションのクエリです。すべての結果を取得するには、このパラメーターを省略してください。 Type: string Examples: Airpeak

Example Request

GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US

Example Response

    {
      "data": [
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Advantage",
          "targeting_value": "2l"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Aeris",
          "targeting_value": "1b"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airadigm",
          "targeting_value": "2t"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airlink PCS",
          "targeting_value": "14"
        },
        {
          "country_code": "US",
          "targeting_type": "NETWORK_OPERATOR",
          "name": "Airpeak",
          "targeting_value": "1i"
        }
      ],
      "request": {
        "params": {
          "country_code": "US",
          "count": 5
        }
      },
      "next_cursor": "o7x9iet1a5u608olj4"
    }

​

GET targeting_criteria/platform_versions

プロモーション商品向けに利用可能な、モバイル OS バージョンに基づくターゲティング条件を取得します。プラットフォームバージョンを指定したターゲティングは、プロモーションアカウントおよびプロモーションツイートで利用できます。これにより、Android 8.0 や iOS 10.0 など、モバイルオペレーティングシステムのポイントリリースまで細かく指定してターゲティングできます。

Resource URL

https://ads-api.x.com/12/targeting_criteria/platform_versions

Parameters

Name	Description
q optional	ターゲティング条件の検索対象を絞り込むための任意のクエリです。このパラメーターを省略すると、すべての結果を取得します。 Type: string Examples: jelly bean

Example Request

GET https://ads-api.x.com/12/targeting_criteria/platform_versions

Example Response

    {
        "data": [
            {...},
            {
                "name": "Ice Cream Sandwich",
                "number": "4.0",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "17"
            },
            {
                "name": "Jelly Bean",
                "number": "4.1",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "18"
            },
            {...}
        ],
        "data_type": "targeting_criterion",
        "request": {
            "params": {}
        }
    }

​

GET targeting_criteria/platforms

プロモーションプロダクト向けに利用可能な、プラットフォームに基づくターゲティング条件を取得します。

Resource URL

https://ads-api.x.com/12/targeting_criteria/platforms

Parameters

Name	Description
count optional	各リクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
q optional	ターゲティング条件の検索範囲を絞り込むための任意のクエリです。このパラメータを省略すると、すべての結果を取得します。 Type: string Examples: ios, blackberry
lang optional	ISO-639-1 言語コードを使用します。指定すると、レスポンスに追加の localized_name 属性が返されます。 Type: int, string Example: fr

Example Request

GET https://ads-api.x.com/12/targeting_criteria/platforms

Example Response

    {
      "data": [
        {
          "name": "iOS",
          "targeting_type": "PLATFORM",
          "targeting_value": "0"
        },
        {
          "name": "Android",
          "targeting_type": "PLATFORM",
          "targeting_value": "1"
        },
        {
          "name": "BlackBerry phones and tablets",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "Mobile web on other devices",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "Desktop and laptop computers",
          "targeting_type": "PLATFORM",
          "targeting_value": "4"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_markets

TV ショーをターゲティングできる利用可能な TV マーケットを取得します。ロケールごとのマーケットを返し、この情報を使用して GET targeting_criteria/tv_shows エンドポイントをクエリできます。

リソース URL

https://ads-api.x.com/12/targeting_criteria/tv_markets

パラメーター

なし

リクエスト例

GET https://ads-api.x.com/12/targeting_criteria/tv_markets

レスポンス例

    {
      "data": [
        {
          "name": "France",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "Chile",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "Germany",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "Netherlands",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "United States",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "Venezuela",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "Brazil",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "Mexico",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "Colombia",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "United Kingdom",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "Argentina",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "Japan",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "Canada",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "Spain",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "Italy",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "United States - Hispanic",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "Ireland",
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_shows

Promoted Products 向けに利用可能な TV 番組ベースのターゲティング条件を取得します。TV 番組ターゲティングは、特定の市場における Promoted ツイートで利用できます。利用可能な市場については、GET targeting_criteria/tv_markets エンドポイントを参照してください。

注記: 1,000 ユーザー未満を含むオーディエンスは、estimated_users の値が 1000 として表示されます。

注記: TV チャンネルおよびジャンルによるターゲティングオプションは、サポートされなくなりました。

Resource URL

https://ads-api.x.com/12/targeting_criteria/tv_shows

Parameters

Name	Description
locale required	利用可能な TV 番組を取得するために照会する tv_market_locale を指定する必須パラメータです。TV マーケットは、GET targeting_criteria/tv_markets から返される locale に基づいて決定されます。 Type: string Example: en-US
count optional	1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 50 Min, Max: 1, 50
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は、Pagination を参照してください。 Type: string Example: 8x7v00oow
q optional	ターゲティング条件の検索を絞り込むための任意のクエリです。すべての結果を取得するには、このパラメータを省略します。 Type: string Examples: ios, blackberry

Example Request

GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1

Example Response

    {
      "data": [
        {
          "name": "NewsWatch",
          "targeting_value": 10027243420,
          "genre": "PAID",
          "locales": [
            {
              "language": "en",
              "country": "US"
            }
          ]
        }
      ],
      "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ",
      "request": {
        "params": {
          "locale": {
            "countryCode": "US",
            "languageCode": "en"
          },
          "count": 1,
          "q": "news"
        }
      }
    }

​

ターゲティング候補

​

GET accounts/:account_id/targeting_suggestions

初期の選択を補完するために、キーワードまたはユーザーのターゲティング候補を最大 50 個まで取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは認証ユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
suggestion_type required	返す候補の種別を指定します。 Type: enum Possible values: KEYWORD, USER_ID
targeting_values required	候補のシードとして使用するキーワードまたはユーザー ID のカンマ区切りの一覧です。 Note: これら 2 種類の候補を混在させることはできません。 Example: 756201191646691328
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 30 Min, Max: 1, 50

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"

Example Response

    {
      "data": [
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "devs"
        },
        {
          "suggestion_type": "KEYWORD",
          "suggestion_value": "software"
        }
      ],
      "request": {
        "params": {
          "suggestion_type": "KEYWORD",
          "targeting_values": [
            "developers"
          ],
          "count": 2,
          "account_id": "18ce54d4x5t"
        }
      }
    }

​

税設定

​

GET accounts/:account_id/tax_settings

現在のアカウントに関連付けられている税設定の詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tax_settings

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "London",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Inc.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

PUT accounts/:account_id/tax_settings

現在のアカウントの税設定を更新します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tax_settings

Parameters

名前	説明
account_id 必須	利用対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
address_city 任意	アカウント所有者の住所に対応する市区町村。 Type: string Example: San Francisco
address_country 任意	アカウント所有者の住所に対応する2文字の国コード。 Type: string Example: US
address_email 任意	アカウント所有者の住所に紐づくメールアドレス。 Type: string Example: [e-mail]
address_first_name 任意	アカウント所有者の住所に紐づく名 (ファーストネーム) 。 Type: string Example: API
address_last_name 任意	アカウント所有者の住所に記載されている姓。 Type: string Example: McTestface
address_name 任意	アカウント所有者の住所に登録されている会社名。 Type: string Example: ABC, Co.
address_postal_code 省略可能	アカウント所有者の住所の郵便番号。 Type: string Example: 94102
address_region 任意	アカウント所有者の住所の州／地域。 Type: string Example: California
address_street1 任意	アカウント所有者の住所の1行目 (番地など) 。 Type: string 例: 21 March St
address_street2 任意	アカウント所有者の住所の 2 行目にあたる情報。 Type: string Example: Suite 99
bill_to 省略可	請求先となる主体。 Type: enum Possible values: ADVERTISER, AGENCY
business_relationship 任意	アカウントが広告主名義か代理店名義かを示します。 Type: enum Possible values: AGENCY, SELF
client_address_city 任意	広告主の住所の市区町村名。 広告アカウントが代理店所有の場合に設定します。 Type: string Example: Toronto
client_address_country 任意項目	広告主の住所の2文字の国コード。 広告アカウントの所有者が代理店である場合に設定します。 Type: string Example: CA
client_address_email 任意	広告主の住所に紐づくメールアドレス。 広告アカウントが代理店所有の場合に設定します。 Type: string Example: [e-mail]
client_address_first_name 任意	広告主の住所に紐づく名 (ファーストネーム) 。 広告アカウントが代理店に所有されている場合に設定します。 Type: string Example: Brand
client_address_last_name 任意	広告主の住所に記載される姓。 広告アカウントが代理店所有の場合に設定します。 Type: string Example: Advertiser
client_address_name 任意	広告主の住所に登録されている会社名。 代理店が広告アカウントを所有している場合に設定します。 Type: string Example: Brand, Inc.
client_address_postal_code 任意	広告主の住所の郵便番号。 広告アカウントの所有者が代理店である場合に設定します。 Type: string Example: M5H 2N2
client_address_region 任意	広告主の住所の地域。 広告アカウントが代理店名義の場合に設定します。 Type: string Example: Ontario
client_address_street1 任意	広告主の住所の1行目 (通り名など) 。 広告アカウントが代理店所有の場合に設定します。 Type: string Example: 280 Queen St W
client_address_street2 任意	広告主の住所の 2 行目。 広告アカウントが代理店所有の場合に設定してください。 Type: string Example: The 6
invoice_jurisdiction 任意	請求書の管轄。 Type: enum Possible values: LOI_SAPIN, NONE, NOT_SET
tax_category 任意	課税を個人として行うか事業者として行うかを指定します。 Type: enum Possible values: BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id 任意	VAT免税ID。 Type: sting 例: 12345
tax_id 任意	VAT 登録ID。 Type: string Possible values: 67890

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "address_name": "ABC Co."
        }
      },
      "data": {
        "tax_id": "GB896391250",
        "address_city": "London",
        "business_relationship": "SELF",
        "address_street1": "21 March St",
        "address_last_name": null,
        "address_company": "ABC, Co.",
        "tax_category": "BUSINESS_WITH_VAT",
        "address_postal_code": "SW1A 1AA",
        "bill_to": "NOT_SET",
        "address_region": "London",
        "address_country": "GB",
        "address_first_name": null,
        "invoice_jurisdiction": "NOT_SET",
        "address_street2": null,
        "address_email": null
      }
    }

​

トラッキングタグ

​

GET accounts/:account_id/tracking_tags

現在のアカウントに関連付けられている一部またはすべてのトラッキングタグの詳細を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
count optional	1 回のリクエストで取得を試行するレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
line_item_ids optional	カンマ区切りの識別子リストを指定することで、特定のラインアイテムに関連付けられたトラッキングタグのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 96uzp
sort_by optional	サポートされている属性を指定して、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
tracking_tag_ids optional	カンマ区切りの識別子リストを指定することで、対象のトラッキングタグのみにレスポンスを絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: 3m82
with_deleted optional	削除済みの結果をレスポンスに含めます。 Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count レスポンス属性を含めます。 Note: このパラメータと cursor は排他的です。 Note: total_count を含むリクエストには、現在 15 分あたり 200 に設定されている、より厳しいレート制限が適用されます。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82

Example Response

    {
      "request": {
        "params": {
          "tracking_tag_ids": [
            "3m82"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "fdwcl",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "tracking_tag_type": "IMPRESSION_TAG",
          "id": "3m82",
          "created_at": "2019-06-26T17:04:26Z",
          "updated_at": "2019-06-26T17:04:26Z",
          "deleted": false
        }
      ]
    }

​

GET accounts/:account_id/tracking_tags/:tracking_tag_id

現在のアカウントに関連付けられている特定のトラッキングタグを取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須のパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
tracking_tag_id required	リクエストで操作対象となるトラッキングタグを指す参照です。 Type: string Example: 555j
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。 Type: boolean Default: false Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Example Response

    {
      "request": {
        "params": {
          "with_deleted": true,
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2020-08-13T23:02:03Z",
        "deleted": false
      }
    }

​

POST accounts/:account_id/tracking_tags

指定したラインアイテムにトラッキングタグを関連付けます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
line_item_id required	リクエストで操作対象となるラインアイテムを示します。 Type: string Example: 8v7jo
tracking_tag_type required	トラッキングタグのタイプです。 Type: enum Possible value: IMPRESSION_TAG, CLICK_TRACKER
tracking_tag_url required	トラッキングパートナーによって提供されるトラッキングタグの URL です。 Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "fdwcl",
          "tracking_tag_type": "IMPRESSION_TAG",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2019-06-26T17:04:26Z",
        "deleted": false
      }
    }

​

PUT accounts/:account_id/tracking_tags/:tracking_tag_id

指定したラインアイテムにトラッキングタグを関連付けます。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
tracking_tag_url required	トラッキングパートナーによって提供されるトラッキングタグ用の URL。 Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Response

    {
      "request": {
        "params": {
          "tracking_tag_id": "3m82",
          "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "fdwcl",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "3m82",
        "created_at": "2019-06-26T17:04:26Z",
        "updated_at": "2022-01-26T17:04:26Z",
        "deleted": false
      }
    }

​

DELETE accounts/:account_id/tracking_tags/:tracking_tag_id

指定したラインアイテムとトラッキングタグとの関連付けを解除します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id

Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
tracking_tag_id required	リクエスト内で操作対象となるトラッキングタグへの参照です。 型: string 例: 555j

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j

Example Response

    {
      "request": {
        "params": {
          "tracking_tag_id": "555j",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "72v2x",
        "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253",
        "tracking_tag_type": "IMPRESSION_TAG",
        "id": "555j",
        "created_at": "2020-08-13T23:02:03Z",
        "updated_at": "2021-08-29T17:12:58Z",
        "deleted": true
      }
    }

​

ユーザー設定

(https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)

​

GET accounts/:account_id/user_settings/:user_id

ユーザー設定を取得します。

Resource URL

https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id

Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメーターです。 指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
user_id required	リクエストで操作対象となるユーザーを示します。スクリーンネームに対応するユーザー ID を取得するには、GET users/lookup を使用します。 Type: long Example: 756201191646691328

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328

Example Response

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "contact_phone_extension": ""
        }
      }

​

PUT accounts/:account_id/user_settings/:user_id

ユーザー設定を更新します。ユーザーコンテキストが必要です。アカウント管理者ではアクセスできません。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id

パラメーター

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパスおよび GET accounts に含まれます。 指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
user_id required	このリクエストで操作対象となるユーザーを指定します。GET users/lookup を使用して、スクリーンネームからユーザー ID を取得します。 Type: long Example: 756201191646691328
notification_email optional	アカウント通知に使用するメールアドレスです。 Type: string Example: [e-mail]
contact_phone optional	連絡先電話番号です。 Type: string Example: 202-555-0128
contact_phone_extension optional	contact_phone の内線番号です。 Type: string Example: 1234

リクエスト例

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='[e-mail]'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"

レスポンス例

      {
        "request": {
          "params": {
            "account_id": "18ce54d4x5t",
            "user_id": "756201191646691328"
            "notification_email": "[e-mail]",
            "subscribed_campaign_events": [
              "ACCOUNT_PERFORMANCE",
              "PERFORMANCE_IMPROVEMENT"
            ]
          }
        },
        "data": {
          "notification_email": "[e-mail]",
          "contact_phone": "",
          "Contact_phone_extension": ""
        }
      }