캠페인 관리

​

Advertiser API

이 API 제품군을 사용하면 X에서 캠페인을 프로그래밍 방식으로 예약하고 광고를 관리할 수 있습니다.

​

무엇을 홍보할 수 있나요?

​

Promoted Ads

• Promoted Ads는 더 많은 사용자에게 도달하거나 기존 팔로워의 참여를 이끌어내고자 하는 광고주가 구매하는 일반 형식의 광고입니다.
• Promoted Ads는 광고주가 X에서 노출 위치에 대해 비용을 지불하는 경우, Promoted 라벨로 명확하게 표시됩니다. 그 외 모든 면에서 Promoted Ads는 일반 광고와 동일하게 동작하며, 리포스트, 답글, 좋아요 등 다양한 상호작용이 가능합니다. 일반적인 게재 규칙을 따르며 POST statuses/update를 사용해 생성됩니다.
• “Promoted-only” Tweets는 POST accounts/:account_id/tweet를 통해 생성되며, Promoted Tweets 캠페인에 사용할 수 있지만 팔로워에게는 노출되지 않고 공개 타임라인에도 표시되지 않습니다. 특정 계정에 대한 promoted-only tweet 목록을 가져오려면 GET accounts/:account_id/scoped_timeline를 사용하십시오.

​

Promoted Accounts

• Promoted Accounts는 사람들이 아직 팔로우하고 있지 않지만 관심을 가질 만한 계정을 추천하는 Who to Follow 기능의 일부입니다. Promoted Accounts는 이용자들이 좋아할 만한 더 다양한 계정을 발견하도록 돕습니다.
• 타임라인용 Promoted Accounts는 Promoted Tweet을 Promoted Account 캠페인과 연결하며, 사용자 타임라인에 노출됩니다.

Promoted Trends는 Ads API에서 제공되지 않습니다.

​

캠페인 및 광고 그룹(라인 아이템)

캠페인은 광고의 일정과 예산을 정의합니다. 광고주는 일일 예산과 전체 예산을 지정합니다. 캠페인은 특정 시작 및 종료 시간을 설정할 수 있으며, 예산이 소진될 때까지 계속 진행되도록 설정할 수도 있습니다. 예산은 광고 계정의 Funding Instruments 중 하나에서 지출됩니다. 캠페인 식별자(:campaign_id)는 X Ads UI에 표시되는 10진수 값을 36진수로 표현한 값입니다.

광고 계정은 최대 200개의 활성 캠페인으로 제한됩니다. 이 한도는 광고주 담당 X Account Manager가 요청에 따라 수동으로 최대 4,000개의 활성 캠페인까지 상향할 수 있습니다. 캠페인은 종료 시간에 도달하거나 삭제될 때까지 활성 상태로 간주됩니다. 일시 중지된 캠페인도 지정된 종료 시간까지는 활성으로 간주됩니다.

라인 아이템은 캠페인에서 정의한 예산을 집행합니다. 라인 아이템은 참여당 입찰가, 프로모션할 Tweet 또는 계정, 그리고 타게팅 규칙을 하나로 묶습니다.

​

분석

X Ads API는 광고 성과를 추적하고 최적화할 수 있는 일련의 분석 엔드포인트를 제공합니다. 자세한 내용은 Analytics 및 Analytics 모범 사례를 참고하세요.

과금(billing) 지표의 경우, 데이터는 이벤트 발생 후 최대 3일이 지나야 최종 확정될 수 있습니다. 그 이전 시점의 데이터는 잠정적인 것으로 간주해야 합니다. 최종 청구 가능 수치는 항상 잠정 수치 이하입니다. 청구 가능 수치는 스팸 및 관련 저품질 트래픽을 반영해 보정된 값입니다. 시간과 관련된 기타 고려 사항은 Timezones를 참고하세요.

​

캠페인 생성 - 단계별 안내

다음 예시는 twurl를 사용해 앱과 사용자를 설치·구성하고 인증까지 완료한 상태라고 가정합니다. twurl은 cURL과 비슷한 명령줄 도구로, X OAuth 인증을 손쉽게 처리합니다. twurl은 Ads API(및 REST API) 기능을 빠르게 테스트하고 디버깅하는 데 유용한 도구입니다. 요청과 응답의 전체 헤더를 확인하려면 -t 옵션으로 호출을 추적하면 되며, 이는 cURL의 -v 옵션과 거의 동일한 역할을 합니다.

이 예제에서는 키워드로 타겟팅하는 Promoted Ads 캠페인을 생성합니다.

1. account 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. funding instrument id를 조회합니다.

이전 단계에서 실행한 명령으로 가져온 account 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, 일일 예산 한도를$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의 입찰가로 Tweet을 프로모션합니다.

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 요청이 필요합니다.

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

이것으로 완료되었습니다! 타겟팅과 예산이 설정된 Timelines용 프로모션 Tweet 캠페인이 이제 활성 상태로 집행되고 있습니다.

​

목표 기반 캠페인

목표 기반 캠페인과 과금 방식은 광고주가 자신의 마케팅 목표와 일치하는 행동에 대해서만 비용을 지불하도록 합니다. 이를 위해서는 라인 아이템에 적절한 objective를 설정해야 합니다.

라인 아이템 작성(write) 엔드포인트에서 사용되고 조회(read) 엔드포인트에서 반환되는 파라미터는 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 목표가 설정되어야 합니다.

참고: 서로 다른 목표를 가진 라인 아이템은 동일한 캠페인에 포함될 수 없습니다.

캠페인 목표	API objective	Tweet 내 미디어	과금 모델
앱 재참여 유도	APP_ENGAGEMENTS	이미지 또는 동영상 앱 다운로드 카드 필수.	CPAC
앱 설치	APP_INSTALLS	이미지 또는 동영상 앱 다운로드 카드 필수.	CPAC 또는 CPI (charge_by를 사용해 설정)
도달	REACH	제한 없음.	CPM
팔로워	FOLLOWERS	Tweet은 필수가 아니지만 권장됩니다. 팔로워 캠페인의 Tweet 미디어에는 제한이 없지만, 텍스트만 있는 Tweet을 권장합니다. 추가 정보	CPF
참여	ENGAGEMENTS	제한 없음.	CPE
동영상 조회수	VIDEO_VIEWS	동영상 대화 카드, 동영상 또는 GIF 필수.	CPV 또는 3초/100% 조회 기준 단가
프리롤(Pre-roll) 조회수	PREROLL_VIEWS	동영상 필수.	CPV 또는 3초/100% 조회 기준 단가
웹사이트 클릭	WEBSITE_CLICKS	웹사이트 카드를 권장하지만 필수는 아닙니다. Tweet에는 반드시 웹사이트 카드 또는 웹사이트 링크 중 하나만 포함되어야 합니다(둘 다 포함 불가).	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). 하나의 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와 사용된 금액의 차이를 의미하지 않습니다. 신용 한도와 자금 배정 금액은 광고주와 맺은 서로 다른 기초 자금 조달 방식과 지출 계약을 반영하므로, 이 둘을 명확히 구분합니다.

​

자금 수단의 유형

신용카드

일반적으로 계정 매니저 없이 셀프 서비스로 운영하는 광고주들이 사용합니다.

신용한도

insertion order(IO)의 형태로 제공되며, 계정 매니저에 의해 설정됩니다.

다중 핸들 신용한도

광고주는 이 유형의 신용한도를 사용해 여러 핸들에 걸쳐 캠페인에 자금을 지원할 수 있습니다. 이 기능은 X Account Manager가 서로 다른 @handle들을 특정 신용한도에 연결해 활성화합니다.

예를 들어, @NikeSB와 @NikeFuel 모두 @Nike 신용한도에 접근할 수 있습니다. 이 자금 수단은 다른 자금 수단과 마찬가지로 사용할 수 있습니다. funding_instrument 엔드포인트로 GET 요청을 보내 데이터를 조회할 수 있습니다. 아래는 예시 응답입니다(CREDIT_LINE type에 주목하세요).

      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
}

이 자금 조달 수단에 특별한 점이 있다면 type 과 이 수단에 연결된 모든 계정에서 공통으로 사용할 수 있다는 사실뿐입니다. 물론 남은 크레딧은 이 자금 조달 수단으로 자금을 받는, 이를 공유하는 모든 계정의 모든 캠페인에 의해 함께 소진됩니다. 특정 신용 한도에 어떤 계정들이 연결되어 있는지에 대한 세부 정보는 API(또는 ads.x.com)를 통해 제공되지 않습니다.

자금 조달 수단 열거형에 대한 자세한 내용은 여기를 클릭하세요.

​

타게팅

타게팅은 Ads API의 핵심 개념입니다. 타게팅은 라인 아이템(line item) 단위로 설정되며, 옵션은 게재 위치(placement)에 따라 달라집니다. 새로운 타게팅 기준을 설정하려면 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 엔드포인트를 참고하세요. 각 노출 위치별로 타게팅 옵션이 다릅니다. 위치(Location), 플랫폼(Platform), 성별(Gender)은 모든 노출 위치에서 사용할 수 있습니다. 그 외 옵션은 노출 위치 유형에 따라 달라집니다.

• X Search: 연령 타게팅, 디바이스, 이벤트, 성별, 키워드 유형(전체), 언어, 위치, 네트워크 활성화, 네트워크 사업자, 플랫폼, 플랫폼 버전, 맞춤 타겟(Tailored Audiences), WiFi 전용
• X Timeline: 연령 타게팅, 디바이스, 이벤트, 팔로워 타겟(Followers Of), 팔로워 유사 타겟(Similar to Followers Of), 성별, 관심사, 언어, 위치, 네트워크 활성화, 네트워크 사업자, 유사 일치 키워드 유형, 파트너 오디언스 유형, 플랫폼, 플랫폼 버전, 리타게팅 유형, 맞춤 타겟(Tailored Audiences), TV 타게팅 유형, WiFi 전용
• X Profiles & Tweet Details: 연령 타게팅, 디바이스, 이벤트, 팔로워 타겟(Followers Of), 팔로워 유사 타겟(Similar to Followers Of), 성별, 관심사, 언어, 위치, 네트워크 활성화, 네트워크 사업자, 유사 일치 키워드 유형, 파트너 오디언스 유형, 플랫폼, 플랫폼 버전, 리타게팅 유형, 맞춤 타겟(Tailored Audiences), TV 타게팅 유형, WiFi 전용

​

타겟팅 타입 이해하기

연령 타겟팅(Age Targeting): 특정 연령 구간에 따라 사용자를 타겟팅합니다. 연령 구간 enum 리스트는 Enumerations 페이지에서 확인할 수 있습니다.

이벤트: 타겟팅에 사용할 이벤트를 지정합니다. 타겟팅에는 (라인 아이템당) 하나의 이벤트만 사용할 수 있습니다. 타겟팅에 사용할 수 있는 이벤트를 찾으려면 GET targeting_criteria/events 엔드포인트를 사용하세요.

성별: 남성(1) 또는 여성(2)을 타겟팅합니다. 모든 사용자를 타겟팅하려면 null로 둡니다.

설치된 App 스토어 카테고리: 이 타겟팅 타입을 사용하면 사용자가 설치했거나 관심을 표시한 App 카테고리에 따라 사용자를 타겟팅할 수 있습니다. 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 섹션을 참고하세요.

언어 타겟팅: 특정 언어를 이해하는 사용자를 타겟팅합니다.

모바일 네트워크 사업자 타겟팅: 광고주가 GET targeting_criteria/network_operators의 타겟팅 타입 NETWORK_OPERATOR를 사용해 모바일 통신사 기준으로 사용자를 타겟팅할 수 있게 합니다.

새 모바일 기기 타겟팅: 타겟팅 타입 NETWORK_ACTIVATION_DURATION과 operator_type LT(미만), GTE(이상)를 사용하여 사용자가 자신의 기기를 통해 처음 X에 접속한 날짜를 기준으로 사용자를 타겟팅합니다.

플랫폼, 플랫폼 버전, 디바이스, 및 WiFi 전용(Wifi-Only): 다양한 기준을 통해 모바일 디바이스를 타겟팅할 수 있습니다. Platforms는 휴대폰을 넓은 범주로 묶어 타겟팅하는 상위 수준 타겟팅 타입입니다. 예시 값으로는 iOS, Android 등이 있습니다. Devices를 사용하면 iPhone 5s, Nexus 4, Samsung Galaxy Note와 같은 특정 모바일 디바이스 사용자를 타겟팅할 수 있습니다. Platform versions를 사용하면 특정 모바일 운영체제 버전(포인트 릴리스 수준까지)의 사용자를 타겟팅할 수 있습니다. 예시로 iOS 7.1, Android 4.4 등이 있습니다. Wifi-Only는 WiFi 네트워크에서 디바이스를 사용하는 사용자만 타겟팅하며, 이 값을 설정하지 않으면 통신사 네트워크와 WiFi 모두를 사용하는 사용자가 타겟팅됩니다.

• 플랫폼과 디바이스 간에 중복이 없다면 둘 다 타겟팅할 수 있습니다. 예를 들어, Blackberry를 플랫폼으로, iPad Air를 디바이스로 동시에 타겟팅할 수 있습니다.
• 디바이스와 OS 버전은 동시에 타겟팅할 수 있습니다. 예를 들어, iPad Air와 iOS >= 7.0을 함께 타겟팅할 수 있습니다.
• 디바이스보다 범위가 더 넓은 플랫폼은 동시에 타겟팅할 수 없습니다. 예를 들어, iOS와 iPad Air를 함께 타겟팅할 수는 없습니다.

[맞춤 잠재고객]/x-ads-api/audiences: 승인된 광고 파트너를 통해 고객 그룹을 타게팅하고 X에서 이들과 연결하세요.

TV 타게팅

TV 프로그램 타게팅: 특정 TV 프로그램에 참여하는 사람들에게 도달합니다. 이 타게팅 기준은 캠페인이 활성 상태인 동안 TV_SHOW 타게팅 type으로 지속적으로 타게팅되도록 구성할 수 있습니다. 사용 가능한 TV 프로그램을 확인하려면 GET targeting_criteria/tv_markets 및 GET targeting_criteria/tv_shows 엔드포인트를 사용하세요.

Tweet 참여자 리타게팅

Tweet 참여자 리타게팅은 광고주가 X에서 자신의 프로모션 Tweet 또는 오가닉 Tweet에 이전에 노출되었거나 참여한 사용자를 여러 기기에 걸쳐 타게팅할 수 있도록 합니다. 이 타게팅을 통해 광고주는 X에서 자신의 콘텐츠를 보았거나 참여한 사람들 중 이후 메시지나 오퍼에 추가로 반응하거나 전환할 가능성이 가장 높은 사람들에게 후속 광고를 집행할 수 있습니다. 사용자는 노출 또는 참여 후 몇 분 이내에 타게팅 대상으로 포함되며, 참여의 경우 최대 90일, 노출의 경우 최대 30일 동안 자격이 유지됩니다.

Tweet 참여자 타게팅 type:

• 타게팅 값으로 IMPRESSION 또는 ENGAGEMENT를 허용하는 ENGAGEMENT_TYPE. 노출된 사용자(IMPRESSION)를 타게팅할지, 참여한 사용자(ENGAGEMENT)를 타게팅할지를 지정합니다.
• CAMPAIGN_ENGAGEMENT는 타게팅 값으로 캠페인 id를 사용합니다. 이 캠페인에서(ENGAGEMENT_TYPE에 따라) 참여했거나 노출된 사용자가 타게팅 대상이 됩니다.
• USER_ENGAGEMENT는 타게팅 값으로 프로모션 대상 사용자 id를 사용하여, 광고주의 오가닉 콘텐츠에(ENGAGEMENT_TYPE에 따라) 노출되었거나 참여한 사용자를 타게팅합니다. 이는 Ads 계정과 연결된 프로모션 사용자 id여야 합니다.

참고: ENGAGEMENT_TYPE은 하나 이상의 유효한 CAMPAIGN_ENGAGEMENT 또는 USER_ENGAGEMENT 값과 함께 필수입니다. 두 가지 Tweet 참여자 타게팅 type을 모두 사용할 수 있으며, 동일한 라인 아이템에서 여러 캠페인을 타게팅할 수 있습니다.

동영상 시청자 타게팅: 동영상 시청자 타게팅은 Tweet 참여자 타게팅을 기반으로, 광고주가 X에서 동영상을 일부 또는 전체 시청한 사용자 그룹을 타게팅할 수 있도록 합니다. 광고주는 오가닉 동영상, 프로모션 동영상 또는 둘 다를 타게팅할 수 있습니다. 프로모션 동영상은 동영상 조회 목표 캠페인이나 라인 아이템으로만 제한되지 않습니다.

동영상 시청자 타게팅 type:

• 동영상을 재생하도록 클릭했거나 자동 재생으로 3초 이상 시청한 사용자를 위한 VIDEO_VIEW
• 동영상의 50%를 시청한 사용자를 위한 VIDEO_VIEW_PARTIAL
• 동영상의 최소 95%를 시청한 사용자를 위한 VIDEO_VIEW_COMPLETE

Tweet 참여자 타게팅과 마찬가지로, ENGAGEMENT_TYPE이 사용될 때는 라인 아이템의 타게팅 기준에 다음 중 하나 또는 둘 다가 포함되어야 합니다.

• CAMPAIGN_ENGAGEMENT는 타게팅 값으로 캠페인 id를 사용합니다. 이 캠페인에서(ENGAGEMENT_TYPE에 따라) 동영상을 시청한 사용자가 타게팅 대상이 됩니다.
• USER_ENGAGEMENT는 타게팅 값으로 프로모션 대상 사용자 id를 사용하여, 광고주의 오가닉 콘텐츠에서(ENGAGEMENT_TYPE에 따라) 동영상을 시청한 사용자를 타게팅합니다. 이는 Ads 계정과 연결된 프로모션 사용자 id여야 합니다.

키워드 type

개념적 개요는 키워드 타게팅 관련 지원 문서를 참조하세요.

• Broad(기본값): 단어의 순서와 관계없이 모든 단어가 일치합니다. 대소문자, 복수형 또는 시제에 민감하지 않습니다. 가능한 경우 자동으로 확장됩니다(예: “car repair”는 “automobile fix”와도 일치). 확장 없이 타게팅하려면 “+boat +jet”처럼 키워드 앞에 + 기호를 추가해야 합니다. + 없이 키워드를 사용하면 Broad Match가 기본값으로 적용됩니다.
• Unordered(사용 중단됨): 단어의 순서와 관계없이 모든 단어가 일치합니다. 대소문자, 복수형 또는 시제에 민감하지 않습니다.
• Phrase: 정확한 키워드 문자열과 일치하지만, 다른 키워드가 추가로 포함될 수 있습니다.
• Exact: 정확히 해당 키워드 문자열과만 일치하며, 다른 키워드는 허용하지 않습니다.
• Negative: 질의 내에 이 키워드들이 어떤 순서로든 모두 포함되어 있는 검색과의 일치를 피합니다. 다른 단어가 포함되어 있어도 동일합니다.
• Negative Phrase: 질의 내에 이 정확한 키워드 문자열이 포함된 검색과의 일치를 피합니다. 다른 단어가 포함되어 있어도 동일합니다.
• Negative Exact: 이 키워드들과 정확히 일치하고 다른 단어는 포함하지 않는 검색과의 일치를 피합니다.  

이모지 타게팅

이모지 타기팅은 키워드 타기팅을 통해 지원됩니다. 이모지 타기팅을 사용하려면, 해당 이모지를 나타내는 Unicode 코드 포인트(예: ‘face with tears of joy’ 이모지(😂)의 경우 U+1F602 (UTF-8에서는 xF0x9Fx98x82))에 대해 키워드 타기팅을 생성하면 됩니다. 허용되는 이모지는 twemoji 리스트에서 확인할 수 있습니다. 특정 이모지를 타기팅하면 해당 이모지의 모든 변형이 함께 타기팅됩니다.

필수/선택 여부와 각 값에 대한 구체적인 세부 사항 요약은 PUT accounts/:account_id/targeting_criteria를 참고하세요.

​

타기팅 기준 조합

업데이트된 캠페인 워크플로우

국가/지역, 성별, 언어, 기기/플랫폼 기준을 사용해 광범위하게 타기팅하는 캠페인을 생성합니다. 광고주는 그런 다음 이 광범위한 타기팅에 추가 타기팅 기준(예: 관심사, 키워드, 팔로워, 맞춤 타겟, TV)을 결합할 수 있습니다. 라인 아이템에 타기팅 기준이 지정되지 않으면, 해당 라인 아이템은 전 세계 모든 사용자를 타기팅합니다.

“Primary” 유형	기타 유형
팔로워	위치
맞춤 타겟	성별
관심사	언어
키워드	기기 및 플랫폼
TV	연령

타기팅 기준은 광고 그룹에 대해 다음과 같이 결합됩니다.

• “Primary” 타기팅 유형은 ∪ 연산(즉, 논리적 합집합)으로 결합됩니다.
• 기타 타기팅 유형은 AND 연산으로 결합됩니다.
• 동일한 유형끼리는 OR 연산으로 결합됩니다.

몇 가지 예시

한눈에 보기: [(팔로워) ∪ (맞춤 타겟) ∪ (관심사) ∪ (키워드)] AND (위치) AND (성별) AND (언어) AND (기기 및 플랫폼)

Geo 예시:

캠페인에서 다음과 같이 타기팅하는 광고 그룹을 원한다고 가정해 보겠습니다.

• 미국, 영국, 캐나다에 있는 X 사용자(위치)
• 여성인 사용자(성별)
• 맞춤 타겟 리스트에서 구성된 사용자(“Primary”)
• 키워드를 기준으로 한 사용자(“Primary”)

타기팅 기준은 다음과 같습니다.

[US OR GB OR CA] AND [Female] AND [맞춤 타겟 ∪ 키워드]

​

추가 예제

• 성별과 지역만 선택하고 기본 조건(primary)은 선택하지 않은 경우: (Male) AND (US OR GB)
• 성별, 지역, 관심사를 선택한 경우: (Female) AND (CA) AND (Computers OR Technology OR Startups)
• 성별, 지역, 관심사, Tailored Audiences, 키워드를 선택한 경우: (Male) AND (GB) AND (Cars ∪ Tailored Audiences for CRM ∪ autocross)

​

예산 집행 속도(Budget Pacing)

광고주는 이제 프로모션 Tweet 및 계정 캠페인에서 일일 예산이 소진되는 속도를 더 세밀하게 제어할 수 있습니다. 기본값인 표준 게재를 사용 설정하면 하루 동안 예산이 고르게 집행되도록 보장합니다.

표준 게재를 꺼 두면, 타게팅 및 경쟁 상황에 따라 하루 중 상당히 이른 시간에 일일 예산이 모두 소진될 수 있을 정도로, 가능한 한 빠르게 노출을 제공하고 참여를 유도합니다. 이를 가속 게재(accelerated delivery)라고 합니다.

시작하기

표준 게재는 모든 캠페인에 기본으로 적용되므로, 이를 끌 의사가 없다면 별도의 조치는 필요하지 않습니다. 특정 캠페인에서 일일 예산을 가능한 한 빠르게 소진하고 싶다면, standard_delivery 파라미터를 false로 설정하여 게재 속도를 가속 게재로 전환하십시오(GET accounts/:account_id/campaigns 참고).

참고 사항

• “하루(Day)”는 X advertiser account 시간대(예: America/Los_Angeles)를 기준으로 합니다.
• 초기 결과에 따르면 표준 게재를 사용할 경우, 하루 전반에 걸쳐 더 일관된 노출을 유지하면서 광고주의 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

​

국가 타게팅 및 게재 요건

캠페인 관리

국가별 타게팅 및 게재 요건은 이 페이지에 정리되어 있습니다. 모든 파트너는 이러한 요건을 반드시 준수해야 합니다.

​

러시아

X의 Ads Policies에서는 광고주가 러시아를 대상으로 러시아어가 아닌 언어로 작성된 광고를 집행하는 것을 금지합니다. 사용자가 러시아를 명시적으로 타기팅하는 경우, 다음 경고 메시지를 사용자에게 표시해야 합니다:

Ads targeting Russia must be in the Russian language.

​

파트너 관리 자금 조달 수단

온보딩 플로우를 통해 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 대시보드를 통해 기존 X app을 조회하고 수정할 수 있습니다. 새 X app을 생성해야 하는 경우, 승인이 완료된 개발자 계정이 필요합니다. X는 운영+샌드박스용 app 1개와 선택적인 샌드박스 전용 app 1개를 허용합니다. X app은 기업이 소유하고 파트너가 관리하는 X 핸들에서 생성해야 합니다.  

​

광고주 온보딩 플로우

광고주 온보딩 플로우는 웹 브라우저를 통해 다음과 같은 방식으로 진행됩니다:

1. 사용자는 파트너의 웹사이트에서 온보딩 플로우를 시작하고, 온보딩하려는 핸들을 입력합니다.
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 authorization 프로세스가 포함됩니다.  

​

온보딩 리디렉트 페이로드

리디렉트용 URL:

https://ads.x.com/link_managed_account

리디렉트 URL은 다음 파라미터와 함께 호출됩니다:

Name	Type	Description
callback_url	URL 인코딩된 문자열	계정 연결 프로세스가 결과와 관계없이 완료된 후 사용자가 리디렉트될 URL입니다. 프로토콜 세부 정보는 파트너 리디렉트 URL 섹션을 참고하세요
client_app_id	integer	관리 파트너를 식별하는 데 사용되는 X API client app id
promotable_user_id	integer	프로모션을 관리 파트너가 관리하게 될 @handle 의 X user_id 입니다. ads.x.com 에 로그인해 연결 프로세스를 완료하는 사용자가 동일한지 확인하는 데 사용됩니다
fi_description	URL 인코딩된 String (최대 255자)	자금 조달 수단 이름입니다. 이 값은 자금 조달 수단이 조회될 때 API의 description 필드에 표시됩니다. funding_instrument 설명이 제공되면 기존 funding_instrument 는 일시 중지되고, 새로운 관리 파트너 자금 조달 수단이 설정됩니다. (동일한 이름으로 이미 존재하는 경우 아무 일도 일어나지 않습니다)
timezone	Area/Location 형식의 String	일일 예산이 적용될 날짜를 결정하고, 청구 금액을 집계할 때 사용되는 표준 시간대입니다
currency	ISO 4217 통화 코드	입찰가를 입력할 때 사용되며, 청구 금액이 청구될 통화입니다
country	ISO 3166-1 alpha 2 국가 코드	계정의 청구 국가입니다
signature	아래에서 설명하는 대로 URL 인코딩 및 base64 인코딩된 바이너리 코드	공유된 secret 과 다른 파라미터를 결합해 호출의 진위성과 파라미터의 유효성을 검증하는 signature 입니다.

​

콜백 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=

이 서명은 그런 다음 signature 파라미터에 (퍼센트 인코딩된 값으로) 원래 URL 끝에 추가됩니다(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 액세스 토큰을 분실한 경우 온보딩 플로우를 다시 진행할 수 있습니다. 온보딩 플로우 구현에서는 사용자가 로그인된 상태여야 합니다. 사용자가 promotable_user_id와 일치하고, 연결된 광고 계정이 존재하며, 모든 것이 정상이라면 사용자는 콜백 URL로 리디렉션되고, 파트너는 OAuth 플로우를 시작하여 access token을 획득할 수 있습니다.  

​

리디렉션 불가 오류 플로우

account link URL이 잘못된 매개변수로 호출되는 경우, 사용자에게는 잘못되었거나 만료된 매개변수가 주어졌을 때 OAuth 플로우에서 표시되는 페이지와 유사한 페이지가 표시됩니다.  

​

PMFI에 대한 지속적인 업데이트

광고주 온보딩이 완료된 후에는 해당 결제 수단을 관리하는 파트너만 PUT accounts/:account_id/funding_instruments/:funding_instrument_id 엔드포인트를 통해 결제 수단을 관리할 수 있습니다.

​

게재 위치(Placements)

X 광고가 노출될 수 있는 위치는 여러 곳이 있습니다. 이는 line item에서 placements 파라미터로 설정합니다. 가능한 값은 다음과 같습니다.

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

line item의 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	✔	✔	✔	✔

Note: TWITTER_PROFILE 게재 위치만 단독으로 지정하는 것은 불가능합니다.

Note: TWITTER_SEARCH에는 키워드 타게팅이 반드시 필요합니다.

Note: REACH objective에는 반드시 TWITTER_TIMELINE 게재 위치가 포함되어야 합니다. ALL_ON_TWITTER, TWITTER_TIMELINE을 포함하는 임의의 게재 위치 조합, 또는 TWITTER_TIMELINE만 단독으로 사용할 수 있습니다.

​

광고 그룹 FAQ

이 문서는 X Ads API의 광고 그룹에 대해 자주 묻는 질문을 모아 정리한 자료입니다.

​

Ad Group란 무엇인가요?

Ad group은 Ads API에서 line item(라인 아이템)이라고도 불리며, 캠페인 하위에 속하며 특정 X 사용자 집합을 대상으로 타게팅 및 입찰을 수행하는 데 사용됩니다. 광고주는 line item에 Tweet 또는 미디어(예: In-stream 광고로 프로모션되는 동영상)를 연결해 이를 프로모션합니다.

​

Ad Group는 어떻게 생성하나요?

Ad Group는 동일한 캠페인 ID에 대해 POST accounts/:account_id/line_items을 여러 번 호출하고, 각 line item에 서로 (완전히 달라도 되는) 타게팅과 Tweet을 연결함으로써 생성됩니다. 캠페인당 line item은 최대 100개까지 허용되며, 하나의 광고 계정당 활성 캠페인은 최대 200개까지 허용됩니다. 모든 캠페인을 통틀어 하나의 광고 계정당 활성 line item은 최대 8,000개까지 허용됩니다.

​

왜 Ad Groups 지원을 추가해야 하나요?

Ad Groups는 광고주가 캠페인을 더 쉽게 구성하고, 최적화하고, 관리할 수 있도록 설계되었습니다.

Ad Groups의 장점은 입찰, 예산, 크리에이티브, 타기팅 전반에 걸친 서로 다른 전략을 비교하고 제어할 수 있다는 점입니다. 여러 개의 Promoted Tweet을 하나의 line item에 연결해 두면, 경매에서는 먼저 해당 그룹에서 가장 성과가 좋을 Tweet을 선택한 뒤, 모든 line item 전체를 통틀어 해당 캠페인에 가장 적합한 Tweet을 선택하게 됩니다. 여러 Ad Groups 각각에 단일 Tweet만 있는 경우에는, 사실상 각 Ad Group에서 더 나은 성과가 예상되는 Tweet이 선택되도록 합니다.

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의 실시간 특성 때문에 타깃팅의 일별 성과가 일자별로 크게 달라질 수 있기 때문입니다.

​

광고 그룹이 단일 라인 아이템보다 성과가 더 좋은가요?

캠페인의 성과는 여러 요소에 따라 달라지며, 결국 Tweet이 성과를 최종적으로 좌우합니다. 라인 아이템은 Tweet이 사용자에게 노출될 후보가 될 수 있는지 여부를 결정하는 요소로 취급됩니다.

동일한 사용자 집합을 타깃팅하는 라인 아이템은 사용자 중복이 있는 것으로 간주됩니다. 가장 성과가 좋은 사용자 집합을 명확하게 식별할 수 있도록, 라인 아이템 간 타깃팅 중복을 줄이는 것이 모범 사례로 여겨집니다.

​

가이드

​

Video Views Preroll Objective

다음 가이드는 Ads API에서 PREROLL_VIEWS 캠페인을 설정하는 데 필요한 단계를 설명합니다. 일반적으로 이러한 캠페인은 크게 두 가지 유형으로 나뉘며, Curated Categories와 Content Categories(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 (타게팅 기준 설정)

​

단계

​

비디오 업로드

비디오 업로드는 두 단계로 진행됩니다:

​

비디오 미디어 업로드

먼저 Chunked media upload 엔드포인트를 사용해 처리를 위해 비디오를 X로 업로드합니다. 이 엔드포인트를 사용할 때 초기 INIT 호출에 media_category=amplify_video 값을 반드시 전달해야 합니다. 비디오는 청크 단위로 업로드합니다. STATUS 응답의 state 가 succeeded 가 되면 다음 단계로 진행할 수 있습니다. 청크 업로드 엔드포인트를 사용한 미디어 업로드에 대한 자세한 내용은 Promoted Video 개요에서 확인할 수 있습니다.

​

동영상을 광고 계정에 추가

STATUS 명령을 사용해 반환된 state가 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
 }
}

​

캠페인 설정

​

캠페인 생성

캠페인과 라인 아이템/광고 그룹을 생성합니다. 라인 아이템은 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 파라미터가 설정되어 있어야 합니다. 이러한 콘텐츠 카테고리는 각각 하나 이상의 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
  }
}

​

퍼블리셔 선택

광고주는 Content 카테고리 또는 Curated 카테고리 중 하나를 타겟팅하도록 설정할 수 있습니다. 자세한 내용은 아래를 참고하세요. 

참고:  라인 아이템은 Curated 또는 Content 카테고리 중 하나만 타겟팅할 수 있으며, 둘 다 동시에 타겟팅할 수는 없습니다. 

​

선별 카테고리

선별 카테고리를 사용하면 광고주는 미리 설정된 퍼블리셔 그룹을 타게팅할 수 있으며, GET curated_categories 엔드포인트를 사용해 조회할 수 있습니다. 이러한 카테고리는 국가별로 구분되므로, 카테고리의 country_code 값을 기준으로 라인 아이템이 해당 국가를 타게팅하도록 설정해야 합니다.

이 카테고리들 중 하나를 사용하려면, 아래 단계를 나열된 순서대로 수행해야 합니다:

1. 라인 아이템이 선별 카테고리의 country_code 값을 기준으로 적절한 국가를 타게팅하도록 설정해야 합니다.
2. POST line_item_curated_categories 엔드포인트를 사용하여 라인 아이템을 특정 curated_category_id와 연관 지어야 합니다. 

참고: 라인 아이템을 선별 카테고리와 연관 지으면 차단 목록(denylist)에 추가할 수 있는 퍼블리셔 수가 5개로 제한됩니다. 특정 퍼블리셔를 차단 목록에 추가하는 데 사용되는 전체 user_id 목록은 GET publishers 엔드포인트를 통해 조회할 수 있습니다. 또한 하나의 라인 아이템은 동시에 하나를 초과하는 선별 카테고리를 타게팅할 수 없습니다.

다음 예시는 선별 카테고리 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
  }
}

​

콘텐츠 카테고리

콘텐츠 카테고리(표준 카테고리라고도 함)는 GET curated_categories 엔드포인트에서 조회할 수 있습니다. 그런 다음 이 카테고리들을 배치 타기팅 기준 엔드포인트를 사용하여 라인 아이템에 타기팅할 수 있습니다. 다음 예시는 특정 콘텐츠 카테고리 id: sr(“News & Current Events”에 매핑됨)를 선택해 라인 아이템에 적용하는 방법을 보여줍니다.

참고: 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 objective는 Promoted Tweet 또는 Card를 사용하지 않는다는 점에 유의하세요. 대신 비디오 크리에이티브는 광고 그룹(라인 아이템)에 연결되고, 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는 큐레이션 카테고리에 대해 유사한 제외 목록을 조회하는 데 사용할 수 있습니다.

참고: 큐레이션 카테고리에서는 publisher_user_id를 최대 5개까지, 콘텐츠 카테고리에서는 user_id를 최대 50개까지 제외할 수 있습니다.

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 제품의 핵심 기능입니다. 타임라인에서의 키워드 타게팅을 사용하면 플랫폼이 사용자의 최근 Tweet에 포함된 키워드를 기반으로 X 사용자를 타게팅할 수 있습니다. 예를 들어, 광고주가 “plan + trip”이라는 순서와 무관한 키워드 조합을 타게팅하고 있고, 캠페인이 진행되는 동안 사용자가 “I’m starting to plan my trip to Cabo, any suggestions?”라는 Tweet을 작성했다면, 그 사용자는 곧 해당 광고주의 Promoted Tweet을 보게 될 수 있습니다.

​

어떻게 작동하나요?

TL;DR: API 관점에서는 이 변경 사항이 매우 단순합니다. 이제 타임라인의 프로모트된 Tweet에 키워드 타게팅을 적용할 수 있습니다. 라인 아이템에 targeting_type을 unordered_keywords 또는 phrase_keywords로 설정하기만 하면 됩니다.

​

빠른 시작 가이드

• placement를 ALL_ON_TWITTER 또는 TWITTER_TIMELINE으로 설정해 새 line item을 생성합니다. POST accounts/:account_id/line_items
• 새로 생성한 이 line item에 대해 타기팅 기준 유형을 BROAD_KEYWORD로 설정하고 키워드 값을 지정합니다. POST accounts/:account_id/targeting_criteria
• PUT accounts/:account_id/targeting_criteria를 사용해 키워드를 업데이트할 수 있습니다.
• 캠페인이 집행되면 line item의 통계를 조회해 성과를 측정합니다. GET stats/accounts/:account_id

​

API 참조 문서

​

계정

Postman에서 실행

​

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	다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	name 기준으로 리소스 범위를 제한하기 위한 선택적 쿼리입니다. Note: 대소문자를 구분하지 않는 접두사 일치(prefix matching)를 수행합니다. 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

참고: 샌드박스 전용

샌드박스 환경에서 광고 계정을 생성합니다.

리소스 URL

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

매개변수

없음

예시 요청

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

예시 응답

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

계정 이름 및/또는 업종을 업데이트합니다.

리소스 URL

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

매개변수

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`

요청 예시

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

응답 예시

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

참고: 샌드박스 전용

샌드박스 환경에서 광고 계정을 삭제합니다.

리소스 URL

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

매개변수

Name	Description
account_id required	해당 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t

예시 요청

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

예시 응답

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

지정된 광고 계정과 연결된 모든 모바일 앱의 세부 정보를 조회합니다.

리소스 URL

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

매개변수

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
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/18ce54d4x5t/account_apps

응답 예시

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

​

계정 이력

Postman에서 실행

​

GET accounts/:account_id/account_history

요청에 지정된 entity_id에 대해 이루어진 변경 사항의 요약을 조회합니다.

참고: 이 엔드포인트는 현재 베타 상태이며 allowlist에 등록되어야 합니다.

리소스 URL

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

파라미터

Name	Description
account_id required	해당 계정의 식별자입니다. Type: string Example: 18ce54d4x5t
count optional	각 요청에서 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	결과의 다음 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 페이지네이션을 참조하세요. Type: string Example: 8x7v00oow
entity_type required	데이터를 조회할 엔티티 type입니다. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	데이터를 조회할 특정 엔티티입니다. Type: string Example: 8u94t
start_time required	ISO 8601 형식으로 표현되는 지정된 시작 시점으로, 조회되는 데이터를 한정합니다. 참고: 분과 초가 0인 정시(whole hours) 단위로만 지정해야 합니다. Type: string Example: 2017-05-19T07:00:00Z
end_time required	ISO 8601 형식으로 표현되는 지정된 종료 시점으로, 조회되는 데이터를 한정합니다. 참고: 분과 초가 0인 정시(whole hours) 단위로만 지정해야 합니다. Type: string Example: 2017-05-26T07:00:00Z
user_id optional	응답을 특정 사용자로 한정합니다. 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"
        }
      ]
    }

​

광고주 비즈니스 카테고리

Postman에서 실행하기

​

GET advertiser_business_categories

광고주의 브랜드를 퍼블리셔에게 설명하기 위해 광고 그룹(line_items)에서 사용할 수 있는 유효한 광고주 비즈니스 categories를 요청합니다.

참고: 이 카테고리는 PREROLL_VIEWS 목표를 가진 line_items에만 적용되며, 타기팅 기준에 사용되는 content_categories와는 별개입니다.

각 advertiser_business_categories는 IAB Categories 집합을 나타냅니다. PREROLL_VIEWS 목표를 가진 광고 그룹을 생성할 때는 하나 또는 두 개의 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": "소비재",
          "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"
          ]
        }
      ]
    }

​

잠재 고객 규모 추정

Postman에서 실행

POST accounts/:account_id/audience_estimate

​

캠페인의 예상 잠재 고객 규모를 파악합니다.

이 엔드포인트는 타기팅 기준 객체의 파라미터를 포함하는 JSON 객체 배열을 입력으로 받습니다. 필수 및 선택적 타기팅 기준 파라미터 목록은 POST accounts/:account_id/targeting_criteria 엔드포인트에서 확인할 수 있습니다. 요청은 반드시 JSON 콘텐츠 본문을 포함하는 HTTP POST 요청이어야 하며, Content-Type: application/json 헤더를 포함해야 합니다.

참고: 최소 하나의 기본(primary) 타기팅 기준을 지정해야 합니다. 모든 기본 타기팅 기준 목록은 캠페인 타기팅 페이지에서 확인할 수 있습니다.

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	타기팅 기준이 가져야 하는 관계를 지정합니다. 예를 들어, 제외(negated) 타기팅을 설정하려면 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
        }
      }
    }

​

인증된 사용자 액세스

Postman에서 실행

​

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 권한은 인증된 사용자가 광고주를 대신하여 nullcasted(또는 “Promoted-only”) Tweet을 생성할 수 있음을 나타냅니다. 이는 ACCOUNT_ADMIN, AD_MANAGER 또는 CREATIVE_MANAGER 권한을 가진 사용자에게만 제공됩니다.

리소스 URL

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

파라미터

없음

요청 예시

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

응답 예시

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

​

입찰 규칙

Postman에서 실행

​

GET bidding_rules

일부 또는 모든 통화에 대한 입찰 규칙을 조회합니다. 응답에는 최소 및 최대 CPE(참여당 비용) 입찰가가 포함됩니다.

이 입찰 규칙은 거의 변경되지 않지만, 시스템에서 최소한 월 1회 이상 이 엔드포인트에서 값을 갱신하도록 설정할 것을 권장합니다.

Resource URL

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

Parameters

Name	Description
currency optional	ISO-4217을 사용해 식별되는, 결과를 필터링할 통화 유형입니다. 이는 “USD” 또는 “EUR”와 같은 세 글자의 문자열입니다. 이 매개변수를 생략하면 인증된 사용자와 연관된 모든 입찰 규칙을 가져옵니다. 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
    }

​

캠페인

Postman에서 실행

​

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

현재 계정과 연결된 새 캠페인을 생성합니다.

참고: 계정당 활성 캠페인의 기본 한도는 200개입니다. 단, 비활성 캠페인 수에는 제한이 없습니다. 이 한도는 최대 8,000개의 활성 캠페인까지 늘릴 수 있습니다. 더 높은 한도를 사용하려면 광고주가 자신의 X Account Manager에게 요청해야 합니다.

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
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	캠페인에 할당할 일일 예산 금액입니다. 지정된 자금 수단과 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표현됩니다. 참고: 이 값은 total_budget_amount_local_micro 이하이어야 하며, 대부분의 Funding Insturment 유형에서 필수입니다. 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

Example Request

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

Example Response

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

단일 요청으로 새로운 캠페인을 일괄 생성할 수 있습니다.

배치 요청

• 현재 최대 배치 크기는 40입니다.
• 모든 매개변수는 요청 본문으로 전송되며, Content-Type은 application/json이어야 합니다.
• 배치 요청은 하나의 그룹으로 함께 실패하거나 성공하며, 오류 및 성공에 대한 모든 API 응답에서 초기 요청의 항목 순서를 그대로 유지합니다.

배치 응답

배치 API 응답은 요청 순서가 유지된 항목 컬렉션을 반환합니다. 이 점을 제외하면, 해당하는 단일 항목 엔드포인트와 구조가 동일합니다.

배치 오류

• 요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 객체 아래에 표시됩니다.
• 항목 수준 오류(예: 필수 캠페인 매개변수 누락)는 응답의 operation_errors 객체 아래에 표시됩니다.

리소스 URL

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

매개변수

Name	Description
operation_type required	각 항목에 대해 수행되는 작업 type입니다. Type: enum Possible values: Create, Delete, Update
params required	캠페인 객체에 대한 모든 매개변수를 포함하는 JSON 객체입니다. 필수 및 선택적 캠페인 매개변수 목록은 여기를 참고하세요.

요청 예시

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

현재 계정과 연결된 지정된 캠페인을 업데이트합니다.

리소스 URL

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

매개변수

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	캠페인에 할당할 일일 예산 금액입니다. 지정된 결제 수단과 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표현됩니다. 이 값을 제공하지 않으면 캠페인은 총 예산과 캠페인 플라이트 기간에 따라 균등하게 집행됩니다. Note: 이 값은 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	발주(Booking) 참조 번호입니다. 청구서 대조에 도움이 되도록 이 필드를 사용하십시오. 최대 길이: 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

요청 예시

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

응답 예시

    {
      "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를 반환합니다.

리소스 URL

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

매개변수

Name	Description
account_id required	해당 계정을 식별하는 값입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
campaign_id required	요청에서 조작 대상이 되는 캠페인에 대한 참조입니다. Type: string Example: 8yn7m

예시 요청

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

예시 응답

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

​

콘텐츠 카테고리

Postman에서 실행하기

​

GET content_categories

라인 아이템의 targeting_criteria로 설정할 수 있는 유효한 콘텐츠 categories를 조회합니다.

각 content_category는 하나 이상의 IAB Categories에 매핑됩니다. 이는 배치 targeting_critera 엔드포인트에서 targeting_type을 IAB_CATEGORY로 설정하고, content_categories 요청에서 반환된 해당 iab_categories 집합을 포함하도록 지정함으로써 수행할 수 있습니다. 이렇게 하지 않으면 검증 오류가 발생합니다.

이러한 각 콘텐츠 카테고리에 대한 퍼블리셔 상세 정보는 GET publishers 엔드포인트를 사용하여 조회할 수 있습니다.

자세한 내용은 Video Views Pre-roll Objective Guide를 참조하세요.

리소스 URL

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

매개변수

요청 매개변수 없음

예시 요청

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

예시 응답

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "자동차 (승용차, 트럭, 레이싱)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "코미디",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "디지털 크리에이터",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "엔터테인먼트 & 대중문화",
          "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": "금융 & 비즈니스 뉴스",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "음식 & 음료",
          "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": "음악",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "뉴스 & 시사",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "정치",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "과학 & 교육",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "스포츠",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "기술",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "텔레비전",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "e스포츠 & 비디오 게임",
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

​

큐레이션 카테고리

Postman에서 실행

​

GET accounts/:account_id/curated_categories

지정된 country_codes에 대해 사용 가능한 큐레이션 카테고리 목록을 가져옵니다.

각 curated_category는 응답의 country_codes로 지정된 특정 국가에서만 사용 가능합니다.

자세한 내용은 Video Views Pre-roll Objective 가이드에서 확인할 수 있습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	대상 계정을 식별하는 값입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
country_codes required	쉼표로 구분된 두 글자의 ISO 국가 코드 목록을 지정하여, 응답을 원하는 국가로만 한정합니다. 최대 200개의 코드를 제공할 수 있습니다. Type: string Example: US
cursor optional	결과의 다음 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow

요청 예시

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

응답 예시

{
      "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": "온라인 게이밍에서 가장 인기 있고 사랑받는 디지털 크리에이터 목록에서 독점 제공되는 최고의 일상 게이밍 콘텐츠 옆에 게재됩니다.",
          "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": "이벤트 중계와 연중 보완 프로그래밍을 모두 다루는 세계 최고의 e스포츠 팀 프로그래밍 옆에 게재됩니다.",
          "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": "대학 팀, 프로 팀, 주요 축구 관련 소식을 공유하는 최고의 스포츠 미디어 계정 등 최고의 일상 축구 콘텐츠와 함께 광고를 게재하세요.",
        "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
      }
    }

​

기능

Postman에서 실행

​

GET accounts/:account_id/features

이 광고 계정에서 사용할 수 있도록 부여된 기능(feature) 컬렉션을 조회합니다. 각 기능은 설명적인 feature key로 표시되며, 베타 또는 그 밖의 제한된 릴리스로 도입되어 Ads API에서 사용 가능한 경우에만 이 엔드포인트를 통해 노출됩니다. 이러한 기준을 충족하지 않는 기능은 이 엔드포인트에서 노출되지 않습니다.

참고: 이 엔드포인트는 Ads API 생태계 개발을 지원하고, 클라이언트의 베타 릴리스 접근 권한에 대한 가시성을 개선하기 위한 목적을 가집니다. API 개발자는 광고주를 대신하여 기능에 대한 접근 권한을 요청할 수 없습니다. 이러한 요청은 광고주가 직접 자신의 X 계정 담당자에게만 할 수 있습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	사용 중인 계정을 식별하기 위한 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에 대해 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: 18ce54d4x5t
feature_keys optional	특정 feature key를 기준으로 조회할 수 있게 해 주는 선택적 매개변수입니다. 요청에는 여러 개의 key를 쉼표로 구분하여 포함할 수 있습니다. 참고: 이 계정에서 접근 가능한 기능만 응답에 포함됩니다. Type: enum Possible values: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

요청 예시

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

응답 예시

    {
      "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 계정에 기능을 추가합니다.

최신 계정 기능 목록은 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"
      ]
    }

​

결제 수단

Postman에서 실행하기

​

GET accounts/:account_id/funding_instruments

현재 계정에 연결된 일부 또는 모든 자금 조달 수단(funding instrument)의 세부 정보를 조회합니다.

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 응답 속성을 포함합니다. 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/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를 조회합니다.

Resource URL

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

Parameters

Name	Description
account_id required	대상 계정(leveraged account)에 대한 식별자입니다. 리소스 경로(path)에 포함되며, 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

Example Request

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

Example Response

    {
      "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 전용

샌드박스 환경에서 자금 조달 수단(funding instrument)을 생성합니다.

샌드박스 자금 조달 수단을 사용하는 동안에는 비용이 발생할 위험이 없습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	레버리지 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: gq1844
currency required	ISO-4217 형식으로 표현된 통화입니다. Type: string Example: USD
start_time required	자금 조달 수단이 활성화되어 사용 가능해지는 일시로, ISO 8601 형식으로 표현됩니다. Type: string Example: 2017-05-19T07:00:00Z
type required	생성할 자금 조달 수단의 유형입니다. Type: enum Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time sometimes required	자금 조달 수단이 비활성화되는 일시로, ISO 8601 형식으로 표현됩니다. Type: string Example: 2017-05-26T07:00:00Z
credit_limit_local_micro optional	이 자금 조달 수단으로 사용할 수 있는 총 신용 한도입니다. Note: 일부 자금 조달 수단 유형에만 적용됩니다. Type: long Example: 37500000
funded_amount_local_micro optional	이 자금 조달 수단에 할당된 총 예산 금액입니다. Note: 일부 자금 조달 수단 유형에만 적용됩니다. Type: long Example: 37500000

요청 예시

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

응답 예시

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(no payment method has been set up yet)",
        "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 전용

샌드박스 환경에서 funding instrument를 삭제합니다.

Resource URL

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

Parameters

Name	Description
account_id required	레버리지된 계정(leveraged account)의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: gq1844
funding_instrument_id required	요청에서 조작하려는 funding instrument를 가리키는 참조 값입니다. Type: string Exampple: 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 카테고리

Postman에서 실행하기

​

GET iab_categories

광고 그룹(line_items)에 사용할 수 있는 유효한 App categories를 조회합니다.

Resource URL

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

Parameters

Name	Description
count optional	각 요청마다 조회할 레코드 수를 지정합니다. 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
        }
      }
    }

​

라인 아이템

Postman에서 실행하기

​

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	쉼표로 구분된 식별자 목록을 지정하여 응답 범위를 특정 자금 수단에 속한 라인 아이템으로만 한정합니다. 최대 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

현재 계정과 연결된 특정 라인 아이템을 조회합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

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

현재 계정의 지정된 캠페인에 연결된 라인 아이템을 생성합니다.

캠페인 내의 모든 라인 아이템은 동일한 product_type 및 objective여야 합니다.

PROMOTED_ACCOUNT product_type을 사용할 때 line_item에 Tweet을 연결하면, 기본 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
목표 필수	이 라인 아이템의 캠페인 목표를 나타냅니다. Type: enum 가능한 값: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements 필수	이 라인 아이템이 노출될 게재 위치입니다. 쉼표로 구분된 placement 값 목록을 지정하세요. Type: enum 가능한 값: 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 가능한 값: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time 필수	라인 아이템이 게재를 시작하는 시각을 ISO 8601 형식으로 표현한 값입니다. Type: string Example: 2017-07-05T00:00:00Z
advertiser_domain 일부 경우 필수	이 광고주의 웹사이트 도메인으로, 프로토콜은 포함하지 않습니다. 참고: 라인 아이템의 placement 값이 PUBLISHER_NETWORK로 설정된 경우 필수입니다. Type: string Example: x.com
android_app_store_identifier 경우에 따라 필수	프로모션 대상 앱의 Google App Store 식별자입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS objective의 경우 android_app_store_identifier 또는 ios_app_store_identifier 중 최소 하나의 앱 스토어 식별자를 설정해야 합니다. Type: string Example: com.twitter.android
bid_amount_local_micro 경우에 따라 필수	이 라인 항목과 연관되는 입찰 금액입니다. 지정된 펀딩 수단에 연결된 통화가 사용됩니다. USD의 경우 5.50달러는 5500000으로 표시됩니다. 참고: bid_strategy가 MAX 또는 TARGET으로 설정된 경우 필수입니다. 참고: 0보다 큰 값만 허용됩니다. Type: long Example: 5500000
categories 경우에 따라 필수	이 광고주에 해당하는 IAB 카테고리입니다. GET iab_categories를 참고하세요. 참고: 라인 아이템의 placement가 PUBLISHER_NETWORK로 설정된 경우 필수입니다. Type: string Example: IAB3-1
ios_app_store_identifier 조건부 필수	프로모션 대상 애플리케이션의 Apple App Store 식별자 중 숫자 부분입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS objective의 경우 android_app_store_identifier 또는 ios_app_store_identifier 중 적어도 하나의 app store 식별자를 설정해야 합니다. Type: string Example: 333903271
primary_web_event_tag 경우에 따라 필수	기본 웹 이벤트 태그의 식별자입니다. 이 라인 아이템에 해당하는 캠페인의 참여를 더 정확하게 추적할 수 있도록 합니다. 참고: 라인 아이템의 목표가 WEBSITE_CONVERSIONS로 설정된 경우 필수입니다. Type: string Example: nvo4z
advertiser_user_id 선택 사항	PREROLL_VIEWS 광고를 프로모션하는 핸들의 X 사용자 식별자입니다. 이 매개변수는 일부 클라이언트 애플리케이션에서만 사용할 수 있습니다. Type: string Example: 312226591
audience_expansion 선택 사항	이미 타깃팅된 사용자와 유사한 사용자를 타깃팅하여 캠페인의 도달 범위를 확장하는 데 사용됩니다. 참고: 기본적으로 확장은 적용되지 않습니다. Type: enum 가능한 값: BROAD, DEFINED, EXPANDED
bid_strategy 선택 사항	입찰 메커니즘입니다. AUTO는 일일 예산과 캠페인 진행 기간을 기준으로 입찰을 자동으로 최적화합니다. MAX는 허용되는 최대 입찰가를 설정하며, 목표(objective)가 REACH 또는 FOLLOWERS로 설정된 경우에는 사용할 수 없습니다. TARGET는 지정된 bid_amount_local_micro의 20% 이내에서 일일 평균 입찰가가 유지되도록 시도하며, 목표(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 선택 사항	한 사용자에게 광고가 노출될 수 있는 최대 횟수입니다. 참고: 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 목표에서만 사용할 수 있습니다. 참고: 목표에 따라 기본값이 결정됩니다. Type: 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와 라인 아이템의 입찰 단위(bid unit)를 기준으로 자동으로 설정됩니다. APP_INSTALLS goal은 APP_CLICK 및 IMPRESSION 값을 모두 지원합니다. 기본값은 IMPRESSION입니다. LINK_CLICKS goal은 LINK_CLICK 및 IMPRESSION 값을 모두 지원합니다. 기본값은 IMPRESSION이지만, bid_strategy에 대해 TARGET을 설정하는 경우에는 지원되지 않습니다. SITE_VISITS goal은 IMPRESSION 값을 지원합니다. Type: enum 가능한 값: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery 선택 사항	표준 또는 가속 게재를 사용하도록 설정합니다. 표준 게재와 가속 게재의 차이에 대한 자세한 내용은 Budget Pacing을(를) 참조하세요. 상위 캠페인에서 budget_optimization이 LINE_ITEM으로 설정된 경우에만 사용할 수 있습니다. Type: boolean 기본값: true 가능한 값: true, false
total_budget_amount_local_micro 선택 사항	라인 아이템에 할당할 총 예산 금액입니다. 지정한 펀딩 인스트루먼트에 연결된 통화가 사용됩니다. USD의 경우 $37.50은 37500000으로 표시됩니다. Type: long Example: 37500000
daily_budget_amount_local_micro 경우에 따라 필수	캠페인에 할당할 일일 예산 금액입니다. 지정된 펀딩 수단과 연결된 통화가 사용됩니다. 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

단일 요청으로 새로운 line items를 일괄 생성할 수 있습니다.

배치 요청

• 현재 최대 배치 크기는 40입니다.
• 모든 파라미터는 요청 본문으로 전송되며 Content-Type은 application/json이어야 합니다.
• 배치 요청은 하나의 그룹으로 함께 실패하거나 성공하며, 오류와 성공에 대한 모든 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: enum Possible values: 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

현재 계정에 연결된 지정된 라인 아이템을 업데이트합니다.

Resource URL

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

Parameters

이름	설명
account_id 필수	사용 중인 계정을 식별하는 값입니다. 이 값은 리소스 경로에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_id 필수	요청에서 작업 중인 line item을 참조하는 값입니다. Type: string 예시: 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 목표의 경우, android_app_store_identifier나 ios_app_store_identifier 중 최소 한 개의 앱 스토어 식별자를 반드시 설정해야 합니다. Type: string Example: com.twitter.android
audience_expansion 선택 사항	기존에 타깃팅된 사용자와 유사한 사용자를 대상으로 캠페인의 도달 범위를 확장하는 데 사용합니다. Type: enum 가능한 값: BROAD, DEFINED, EXPANDED
bid_amount_local_micro 선택 사항	이 line item에 설정될 입찰 금액입니다. 지정된 자금원에 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표시됩니다. 참고: bid_strategy가 MAX 또는 TARGET으로 설정된 경우 필수입니다. 참고: 0보다 큰 값만 허용됩니다. Type: long Example: 140000
bid_strategy 선택 사항	입찰 방식입니다. AUTO는 일일 예산과 캠페인 기간을 기준으로 입찰을 자동으로 최적화합니다. MAX는 허용되는 최대 입찰가를 설정하며, objective가 REACH 또는 FOLLOWERS로 설정된 경우에는 사용할 수 없습니다. TARGET는 지정된 bid_amount_local_micro 값을 기준으로 일일 평균 입찰가를 해당 값의 20% 이내로 유지하도록 시도하며, objective가 REACH 또는 WEBSITE_CLICKS로 설정된 경우에 사용할 수 있습니다. 참고: AUTO로 설정하면 bid_amount_local_micro는 무시됩니다. 참고: objective에 따라 기본값이 결정됩니다. Type: enum Possible values: AUTO, MAX, TARGET
카테고리 선택 사항	해당 광고주의 관련 IAB 카테리입니다. GET iab_categories를 참고하세요. 참고: 라인 아이템의 placement 값이 PUBLISHER_NETWORK로 설정된 경우 필수입니다. Type: string Example: IAB3-1
duration_in_days 선택 사항	frequency_cap이 달성되는 기간(일 단위)입니다. Type: int 가능한 값: 1, 7, 30
entity_status 선택 사항	라인 아이템의 상태입니다. Type: enum 가능한 값: ACTIVE, PAUSED
end_time 선택 사항	라인 아이템의 집행이 종료되는 시간을 ISO 8601 형식으로 표현한 값입니다. Type: string 예시: 2017-10-05T00:00:00Z
frequency_cap 선택 사항	하나의 사용자에게 광고가 노출될 수 있는 최대 횟수입니다. 참고: REACH, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS 캠페인 목표에서만 지원됩니다. Type: int Example: 5
goal 선택 사항	이 라인 아이템에 사용할 최적화 설정입니다. APP_PURCHASES 옵션은 APP_INSTALL에 사용할 수 있습니다. APP_CLICKS 및 APP_INSTALLS 옵션은 APP_INSTALL 및 APP_ENGAGEMENTS에 사용할 수 있으며, 지원되는 MACT 파트너를 사용해야 할 수도 있습니다. 참고: 기본값은 objective에 따라 결정됩니다. Type: enum 가능한 값: 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 ID의 숫자 부분입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS 목표의 경우 android_app_store_identifier 또는 ios_app_store_identifier 중 적어도 하나의 앱 스토어 ID를 설정해야 합니다. Type: string Example: 333903271
name 선택 사항	라인 아이템 이름입니다. Type: string Example: demo
pay_by 선택 사항	이 라인 아이템의 과금 기준 단위입니다. 이 설정은 APP_INSTALLS objective를 사용하는 라인 아이템에만 수정할 수 있습니다. 참고: 기본 pay_by 값은 캠페인 objective와 라인 아이템의 입찰 단위(bid unit)에 따라 자동으로 설정됩니다. APP_INSTALLS goal은 APP_CLICK 및 IMPRESSION 값을 모두 지원합니다. 기본값은 IMPRESSION입니다. LINK_CLICKS goal은 LINK_CLICK 및 IMPRESSION 값을 모두 지원합니다. 기본값은 IMPRESSION이지만, bid_strategy에 대해 TARGET을 설정하는 경우에는 이 값은 지원되지 않습니다. SITE_VISITS goal은 IMPRESSION 값만 지원합니다. Type: enum 가능한 값: 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 선택사항	캠페인에 할당될 일일 예산 금액입니다. 지정된 펀딩 수단과 연관된 통화가 사용됩니다. 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

현재 계정에 속한 지정된 라인 아이템을 삭제합니다.

Note: 라인 아이템 삭제는 되돌릴 수 없으며, 이후에 해당 리소스를 다시 삭제하려는 시도는 HTTP 404를 반환합니다.

Note: 라인 아이템이 삭제되면, 해당 라인 아이템의 하위 리소스인 promoted_tweets는 요청에 with_deleted=true가 지정된 경우에만 GET accounts/:account_id/promoted_tweets 및 GET accounts/:account_id/promoted_tweets/:promoted_tweet_id 엔드포인트에서 반환됩니다. 이러한 promoted_tweets는 실제로 삭제되지는 않습니다(응답에서 "deleted": false). 삭제 작업은 하위 리소스로 연쇄(cascade)되지 않습니다.

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

​

라인 아이템 선별 카테고리

Postman에서 실행

사용 방법에 대한 자세한 내용은 Video Views 프리롤 Objective 가이드에서 확인할 수 있습니다.

​

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	다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 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

지정한 라인 아이템 큐레이티드 카테고리를 업데이트합니다.

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	요청에서 사용 중인 라인 아이템 큐레이티드 카테고리에 대한 참조입니다. Type: string Example: 1bzq3
curated_category_id optional	요청에서 사용 중인 큐레이티드 카테고리 엔티티에 대한 참조입니다. Type: string Example: 10miy
line_item_id optional	요청에서 사용 중인 라인 아이템에 대한 참조입니다. 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
      }
    }

​

라인 아이템 게재 위치

Postman에서 실행

​

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

​

미디어 크리에이티브

Postman에서 실행

​

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	각 요청에서 조회를 시도할 레코드 수를 지정합니다. 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

현재 계정과 연결된 특정 media creative의 세부 정보를 조회합니다.

리소스 URL

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

매개변수

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
media_creative_id required	요청에서 조작하려는 media creative를 가리키는 참조 값입니다. Type: string Example: 43853bhii885
with_deleted optional	요청 결과에 삭제된 항목을 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

요청 예시

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

응답 예시

    {
      "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 오브젝트를 연결합니다.

이 엔드포인트를 사용하여 인스트림 광고(계정 미디어의 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”)에만 사용해야 합니다. 이 값은 프리롤 에셋과 함께 사용될 경우 무시됩니다. 프리롤 에셋에 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
      }
    }

​

홍보 계정

Postman에서 실행

​

GET accounts/:account_id/promoted_accounts

현재 계정의 하나 이상의 라인 아이템에 연결된 일부 또는 모든 프로모션 계정에 대한 세부 정보를 조회합니다.

응답의 user_id로 식별되는 사용자 계정에 대한 사용자 데이터를 얻으려면 GET users/lookup을 사용하세요.

지정한 라인 아이템 중 어느 것도 프로모션 계정을 포함하도록 구성되지 않은 경우 HTTP 400이 반환됩니다.

리소스 URL

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

매개변수

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

예시 요청

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

예시 응답

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

현재 account의 line item에 연결된 특정 계정 참조를 조회합니다.

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 요청에서 일반적으로 필수 매개변수입니다. 지정된 account는 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
promoted_account_id required	요청에서 사용 중인 promoted account에 대한 참조입니다. 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에 대한 자세한 내용은 캠페인 관리 페이지를 참조하세요.

참고: 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	이 요청에서 대상으로 하는 사용자에 대한 참조입니다. screen name에 대한 user 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"
        }
      }
    }

​

프로모션 Tweet

Postman에서 실행

​

GET accounts/:account_id/promoted_tweets

현재 계정의 라인 아이템에 연결된 Tweet에 대한 참조를 조회합니다.

Tweet 객체를 가져오려면 GET accounts/:account_id/tweets 엔드포인트를 사용하세요. 각 promoted_tweets 객체에 대해 tweet_id 값을 사용합니다.

참고: 상위 라인 아이템이 삭제된 경우, 요청에 with_deleted=true가 지정된 경우에만 promoted_tweets가 반환됩니다. 단, 이 promoted_tweets는 실제로 삭제되지 않습니다(응답에서 "deleted": false).

리소스 URL

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

매개변수

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	쉼표로 구분된 식별자 목록을 지정하여, 특정 라인 아이템과 연결된 Tweet만 응답에 포함되도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 96uzp
promoted_tweet_ids optional	쉼표로 구분된 식별자 목록을 지정하여, 원하는 promoted Tweet만 응답에 포함되도록 범위를 제한합니다. 최대 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

요청 예시

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

응답 예시

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

현재 계정의 라인 아이템에 연관된 특정 Tweet 참조를 조회합니다.

참고: 상위 라인 아이템이 삭제된 경우, 요청에서 with_deleted=true를 지정한 경우에만 promoted_tweets가 반환됩니다. 이 promoted_tweets는 실제로 삭제된 것이 아닙니다(응답에서 "deleted": false).

리소스 URL

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

파라미터

Name	Description
account_id required	대상 계정의 식별자입니다. 리소스 경로 내에 나타나며, GET accounts를 제외한 모든 Advertiser API 요청에 대해 일반적으로 필수 파라미터입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	요청에서 다루고 있는 promoted Tweet에 대한 참조입니다. Type: string Example: 1efwlo
with_deleted optional	요청에 삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

예시 요청

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

예시 응답

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

지정된 라인 아이템에 하나 이상의 Tweet을 연결합니다. 캠페인 목표에 따라 모든 Tweet이 프로모션에 적합한 것은 아닙니다. 자세한 내용은 Objective-based Campaigns를 참고하세요.

PROMOTED_ACCOUNT product type을 사용할 때 line_item에 Tweet을 연결하면 기본 PROMOTED_ACCOUNT 노출에 더해 모바일 타임라인 노출이 추가됩니다.

참고: 프로모션 Tweet 엔티티는 업데이트(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	특정 Tweet에 해당하는 식별자의 쉼표로 구분된 목록입니다. 최대 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

지정된 라인 아이템에서 해당 Tweet과의 연관을 해제합니다.

Note: 삭제된 promoted_tweets 엔티티는 ads.x.com UI에서 “Paused”로 표시됩니다. 마찬가지로 UI에서 “pausing”을 수행하면 해당 Tweet은 라인 아이템과의 연관이 해제됩니다.

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

​

프로모션 대상 사용자

Postman에서 실행

​

GET accounts/:account_id/promotable_users

현재 계정과 연결된 프로모션 가능 사용자(promotable user)의 일부 또는 전부에 대한 상세 정보를 가져옵니다.

프로모션 가능 사용자 유형은 FULL 또는 RETWEETS_ONLY 중 하나입니다. 이는 해당 계정이 프로모션할 수 있는 콘텐츠의 유형을 결정합니다. 광고주는 다른 사용자의 콘텐츠를 프로모션하려면 허가를 받아야 하며, 해당 사용자를 RETWEETS_ONLY 프로모션 가능 사용자로 계정에 추가해 달라고 Twitter에 연락해야 합니다.

권한이 올바르게 설정되어 있다면, 프로모션하려는 Tweet의 Tweet ID를 직접 참조하는 프로모션용 제품 엔드포인트에 요청을 보낼 수 있습니다. 게시된 Tweet을 프로모션하려면 POST accounts/:account_id/promoted-tweets 엔드포인트를 사용할 수 있고, 다른 Twitter Ads 계정의 예약된 Tweet을 프로모션하려면 POST accounts/:account_id/scheduled-promoted-tweets 엔드포인트를 사용할 수 있습니다.

대상 Tweet을 리트윗할 필요는 없습니다. 이 방식으로 Tweet을 프로모션하면, 반환되는 tweet_id는 제공한 Tweet ID와 달라집니다. 내부적으로는 해당 Tweet이 nullcast된(nullcasted) Tweet으로 리트윗된 다음 프로모션됩니다. 반환되는 tweet_id는 이 새 Tweet에 해당합니다.

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	다음 페이지 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 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와 달라집니다. 내부적으로는 해당 트윗이 널캐스트된 트윗(nullcasted Tweet)으로 리트윗된 다음 프로모션됩니다. 반환되는 tweet_id는 이 새 트윗에 해당합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

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

​

게시자

Postman에서 실행하기

​

GET publishers

콘텐츠 카테고리 퍼블리셔의 상세 정보 리스트를 조회합니다.

자세한 내용은 Video Views Preroll Objective Guide에서 확인할 수 있습니다.

리소스 URL

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

매개변수

요청 매개변수는 없습니다.

요청 예시

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

응답 예시

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

​

추천 항목

Postman에서 실행

​

GET accounts/:account_id/recommendations

상태: 비공개 베타

이 광고 계정과 연결된 캠페인 추천을 조회합니다. 현재 결제 수단(funding instrument)당 최대 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

상태: 클로즈드 베타

이 광고 계정과 연관된 특정 캠페인 추천 정보를 조회합니다.

캠페인 추천에는 객체 트리 형태로 표현된 캠페인 구조에 대한 전체 변경 제안 세트가 포함됩니다. 응답 트리는 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": "Campaign for recommendations",
                "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": "election results",
                    "targeting_value": "election results",
                    "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": "Male",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "샌프란시스코-오클랜드-산호세 CA, 미국",
                    "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": "Partner audience targeting",
                    "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": "debate",
                    "targeting_value": "debate",
                    "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": "Recommendation for testing",
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

예약된 프로모션 Tweet

Postman에서 실행

​

GET accounts/:account_id/scheduled_promoted_tweets

현재 계정과 연결된 예약된 프로모션용 Tweet 일부 또는 전체에 대한 세부 정보를 조회합니다.

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	다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
line_item_ids optional	쉼표로 구분된 식별자 목록을 지정하여, 특정 라인 아이템(line item)과 연결된 예약된 Tweet만 응답에 포함되도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 8xdpe
scheduled_promoted_tweet_ids optional	쉼표로 구분된 식별자 목록을 지정하여, 원하는 예약된 프로모션용 Tweet만 응답에 포함되도록 범위를 제한합니다. 최대 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

현재 계정과 연관된 특정 예약된 프로모션 Tweet을 조회합니다.

Resource URL

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

Parameters

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스의 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	요청에서 작업 대상으로 하는 예약된 프로모션 Tweet을 가리키는 참조입니다. Type: string Example: 1xboq
with_deleted optional	결과에 삭제된 항목을 포함합니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

지정된 라인 아이템에 예약된 Tweet을 연결합니다.

참고: 예약 프로모션 Tweet 엔티티는 업데이트(PUT)할 수 없습니다.

리소스 URL

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

매개변수

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	요청에서 작업 중인 예약된 Tweet에 대한 참조입니다. Type: long Example: 870358555227860992

요청 예시

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

응답 예시

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

지정된 라인 아이템에서 예약된 Tweet의 연결을 해제합니다.

참고: scheduled_promoted_tweets는 예약된 Tweet의 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	요청에서 대상으로 하는 예약된 프로모션 Tweet에 대한 참조입니다. 이는 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"
        }
      }
    }

​

타겟팅 조건

Postman에서 실행

​

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	요청별로 조회를 시도할 레코드 수를 지정합니다. 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 응답 속성을 포함합니다. 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/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": "Custom audience targeting",
          "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

현재 계정과 연결된 특정 타게팅 기준을 조회합니다.

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	요청에서 사용하려는 타게팅 기준에 대한 참조입니다. 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

Example Request

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

Example Response

    {
      "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 값 세트를 사용하고 있는지 확인하기 위해, 모든 데이터를 매주 한 번씩 갱신할 것을 권장합니다. 값과 사용 가능한 타게팅 기준은 수시로 변경되며, 대부분은 자주 바뀌지 않지만 일부는 자주 변경될 수 있습니다. 이러한 값이 변경되지 않으리라는 보장은 없습니다.

BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD 타게팅 type을 targeting_value에 지정된 키워드와 함께 사용하세요. 키워드를 제외하려면 요청 파라미터 operator_type을 NE로 설정하세요. 각 type에 대한 자세한 설명은 targeting keyword types을 참고하세요.

참고: 각 라인 아이템(line item)마다 하나의 연령 버킷만 타게팅할 수 있습니다.

참고: Custom Audience를 타게팅하려면, 해당 Audience가 타게팅 가능해야 합니다. 즉, targerable 값이 반드시 true여야 합니다.

참고: 타게팅 type TV_SHOW를 사용할 때는, TV_SHOW 타게팅을 설정하기 전에 해당 라인 아이템에 최소 하나의 LOCATION 타게팅 기준이 있어야 하며, 모든 LOCATION은 타게팅 중인 TV_SHOW와 동일한 로케일(locale) 내에 있어야 합니다.

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_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 참고: 각 라인 아이템마다 하나의 AGE 버킷만 타게팅할 수 있습니다. 키워드 기반의 가능한 값은 다음과 같습니다: 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

Example Request

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

단일 요청으로 여러 개의 새로운 타기팅 기준(Targeting Criteria)을 일괄 생성할 수 있습니다.

배치 요청(Batch Requests)

• 현재 최대 배치 크기는 500입니다.
• 모든 매개변수는 요청 본문에 포함되며, Content-Type으로 application/json이 필요합니다.
• 배치 요청은 그룹 단위로 전부 실패하거나 전부 성공하며, 성공 및 오류에 대한 모든 API 응답에서 초기 요청의 항목 순서가 그대로 유지됩니다.

배치 응답(Batch Responses)

배치 API 응답은 순서가 보장된 항목 컬렉션을 반환합니다. 이 점을 제외하면 해당 단일 항목 엔드포인트와 구조적으로 동일합니다.

배치 오류(Batch Errors)

• 요청 수준 오류(예: 최대 배치 크기 초과)는 응답의 errors 객체 아래에 표시됩니다.
• 항목 수준 오류(예: 필수 타기팅 기준(Targeting Criteria) 매개변수 누락)는 응답의 operation_errors 객체 아래에 표시됩니다.

리소스 URL

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

매개변수

Name	Description
operation_type required	항목별로 수행되는 작업 유형입니다. Type: enum 가능한 값: Create, Delete
params required	타기팅 기준 객체에 대한 모든 매개변수를 포함하는 JSON 객체입니다. 필수 및 선택 타기팅 기준 매개변수 목록은 여기를 참고하세요. 추가로, 이 엔드포인트는 특정 targeting_type 값과 함께 동작하는 operator_type 매개변수를 지원합니다. 이 매개변수의 가능한 값은 같음을 의미하는 EQ, 크거나 같음을 의미하는 GTE, 작음을 의미하는 LT, 같지 않음을 의미하는 NE입니다.

요청 예제

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	이 요청에서 대상으로 하는 타기팅 기준에 대한 참조입니다. 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"
        }
      }
    }

​

타겟팅 옵션

Postman에서 실행

• App Store 카테고리
• 대화
• 디바이스
• 이벤트
• 관심사
• 언어
• 위치
• 통신사
• 플랫폼 버전
• 플랫폼
• TV 시장
• TV 프로그램

​

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	각 요청마다 조회를 시도할 레코드 수를 지정합니다. 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

Promoted Products에 사용할 수 있는 기기 기반 타기팅 기준을 조회합니다. 기기 타기팅은 Promoted Tweets에 사용할 수 있습니다.

Resource URL

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

Parameters

Name	Description
count optional	각 개별 요청에서 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
q optional	타기팅 기준을 범위 지정하기 위한 선택적 쿼리입니다. 이 매개변수를 생략하면 모든 기준을 조회합니다. Type: string Example: apple

Example Request

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

Example Response

    {
      "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에 사용할 수 있는 이벤트 기반 타게팅 기준을 조회합니다. 각 line item(라인 아이템)당 하나의 이벤트만 타게팅할 수 있습니다.

Note: 이벤트는 종종 여러 시간대에 걸쳐 존재하므로, 서로 다른 시간대 관점에서 이벤트 시간을 고려할 때 복잡성이 생길 수 있습니다. 이를 단순화하기 위해, 이 엔드포인트의 모든 이벤트 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	각 개별 요청에서 조회를 시도할 레코드 개수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
country_codes optional	2자리 ISO 국가 코드를 사용하여 특정 국가로 타게팅 기준 검색 범위를 제한하기 위한 선택적 쿼리입니다. 이 파라미터를 지정하지 않으면 모든 이벤트가 반환됩니다. Type: string
cursor optional	다음 페이지의 결과를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: 8x7v00oow
end_time optional	캠페인이 종료되는 시간을 ISO 8601 형식으로 지정합니다. Type: string Example: 2017-10-05T00:00:00Z
start_time optional	line item이 노출을 시작하는 시간을 ISO 8601 형식으로 지정합니다. Note: 기본값은 현재 시간입니다. 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

프로모티드 제품(Promoted Products)에 사용할 수 있는 관심사 기반 타겟팅 기준을 확인합니다. 관심사 목록은 자주 변경되지 않지만, 최소 주 1회 이 리스트를 새로 조회할 것을 권장합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

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

타겟팅에 사용할 수 있는 언어 목록을 조회합니다.

리소스 URL

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

매개변수

Name	Description
count optional	각 요청당 조회할 레코드 수를 지정합니다. Type: int 기본값: 200 최솟값, 최댓값: 1, 1000
cursor optional	결과의 다음 페이지를 가져오기 위한 cursor를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string 예시: 8x7v00oow
q optional	타겟팅 기준을 지정하기 위한 선택적 query입니다. 이 매개변수를 생략하면 모든 항목을 조회합니다. Type: string 예시: english

요청 예시

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

응답 예시

    {
      "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을 사용합니다.

Designated Market Areas(DMA)를 타게팅하려면 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

Promoted Products에 사용할 수 있는 모바일 OS 버전 기반 타기팅 기준을 조회합니다. 플랫폼 버전 타기팅은 Promoted Accounts 및 Promoted Tweets에 사용할 수 있습니다. 이를 통해 Android 8.0 또는 iOS 10.0과 같은 모바일 운영체제 버전의 포인트 릴리스(세부 버전) 수준까지 타기팅할 수 있습니다.

리소스 URL

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

매개변수

Name	Description
q optional	타기팅 기준 검색 범위를 한정하기 위한 선택적 쿼리입니다. 모든 결과를 가져오려면 이 매개변수를 생략하세요. Type: string Examples: jelly bean

예시 요청

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

예시 응답

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

Promoted Products에 사용할 수 있는 플랫폼 기반 타게팅 기준을 조회합니다.

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 엔드포인트를 쿼리하는 데 사용할 수 있습니다.

Resource URL

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

Parameters

없음

Example Request

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

Example Response

    {
      "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 Tweet에 대해 사용할 수 있습니다. 지원되는 마켓 목록은 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	각 요청마다 가져올 레코드 수를 지정합니다. 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"
        }
      }
    }

​

타게팅 추천

Postman에서 실행

​

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: 이 두 가지 제안 유형은 혼합해서 사용할 수 없습니다. Example: 756201191646691328
count optional	각 요청에서 조회를 시도할 레코드 수를 지정합니다. 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"
        }
      }
    }

​

세금 설정

Postman에서 실행

​

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 선택 사항	계정 소유자 주소에 대한 두 글자로 된 국가 코드입니다. Type: string Example: US
address_email 선택 사항	계정 소유자의 주소와 연결된 이메일 주소입니다. Type: string Example: [e-mail]
address_first_name 선택 사항	계정 소유자의 주소에 해당하는 이름(First name). Type: string Example: API
address_last_name 선택 사항	계정 소유자 주소의 성입니다. Type: string Example: McTestface
address_name 선택 사항	계정 소유자 주소에 해당하는 회사명입니다. Type: string 예시: ABC, Co.
address_postal_code 선택 사항	계정 소유자 주소의 우편번호입니다. Type: string Example: 94102
address_region 선택 사항	계정 소유자 주소의 지역입니다. Type: string 예시: California
address_street1 선택 사항	계정 소유자의 주소 첫 줄입니다. Type: string Example: 21 March St
address_street2 선택 사항	계정 소유자의 주소 두 번째 주소 줄입니다. Type: string Example: Suite 99
bill_to 선택 사항	청구가 이루어지는 주체입니다. Type: enum 가능한 값: ADVERTISER, AGENCY
business_relationship 선택 사항	계정이 광고주 소유인지 에이전시 소유인지 나타냅니다. Type: enum 가능한 값: AGENCY, SELF
client_address_city 선택 사항	광고주의 주소 도시입니다. 광고 계정이 대행사 소유인 경우 설정합니다. Type: string 예시: Toronto
client_address_country 선택 사항	광고주의 주소가 위치한 국가의 두 글자 국가 코드입니다. 광고 계정이 대행사 소유인 경우 설정합니다. Type: string Example: CA
client_address_email 선택 사항	광고주 주소와 연결된 이메일입니다. 광고 계정을 대행사가 소유한 경우에 설정합니다. Type: string Example: [e-mail]
client_address_first_name 선택 사항	광고주 주소의 이름(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 선택 사항	광고주의 주소 중 거리(street) 항목입니다. 광고 계정이 대행사 소유인 경우에 설정합니다. Type: string Example: 280 Queen St W
client_address_street2 선택 사항	광고주의 주소 두 번째 줄입니다. 광고 계정이 에이전시가 소유한 계정인 경우 설정합니다. Type: string 예시: The 6
invoice_jurisdiction 선택 사항	송장 발행 관할 지역. Type: enum 가능한 값: LOI_SAPIN, NONE, NOT_SET
tax_category 선택 사항	과세 유형이 개인인지 사업자인지 여부입니다. 유형: enum 가능한 값: BUSINESS_NO_VAT, BUSINESS_WITH_VAT, INDIVIDUAL
tax_exemption_id 선택 사항	VAT 면제 ID. 유형: string 예시: 12345
tax_id 선택 사항	VAT 등록 번호. Type: string 가능한 값: 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
      }
    }

​

추적 태그

Postman에서 실행

​

GET accounts/:account_id/tracking_tags

현재 계정과 연결된 일부 또는 모든 트래킹 태그의 세부 정보를 조회합니다.

리소스 URL

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

매개변수

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
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 응답 속성을 포함합니다. 참고: 이 매개변수와 cursor는 상호 배타적입니다. 참고: total_count를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200회로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

요청 예시

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

응답 예시

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

현재 계정과 연결된 특정 트래킹 태그를 조회합니다.

리소스 URL

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

매개변수

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

예시 요청

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

예시 응답

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

지정된 라인 아이템에 추적 태그를 연결합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

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

지정된 라인 아이템에 추적 태그를 연결합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

    {
      "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 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
tracking_tag_id required	요청에서 다루는 추적 태그를 참조하는 값입니다. Type: string Example: 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
      }
    }

​

사용자 설정

Postman에서 실행

(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 예시: 18ce54d4x5t
user_id required	이 요청에서 작업을 수행하는 사용자에 대한 참조입니다. 특정 screen name에 해당하는 user ID를 가져오려면 GET users/lookup을 사용하세요. Type: long 예시: 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

사용자 설정을 업데이트합니다. 사용자 컨텍스트가 필요하며, 계정 관리자는 이 엔드포인트에 액세스할 수 없습니다.

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스의 경로와 GET accounts에 나타납니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
user_id required	요청에서 작업을 수행할 대상 사용자를 참조합니다. 특정 스크린 네임의 사용자 ID를 가져오려면 GET users/lookup을 사용하세요. 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

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='[e-mail]'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"

Example Response

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