캠페인 관리

​

Advertiser API

API 제품군을 통해 X에서 캠페인을 프로그램적으로 일정에 맞춰 운영하고 광고를 관리하세요.

​

어떤 것을 홍보할 수 있나요?

​

프로모션 광고

• 프로모션 광고는 더 많은 사용자에게 도달하거나 기존 팔로워의 참여를 이끌어내고자 하는 광고주가 구매하는 일반 광고입니다.
• 광고주가 X에서 노출 비용을 지불하는 경우 프로모션 광고에는 ‘프로모션’ 레이블이 명확히 표시됩니다. 그 외에는 일반 광고와 동일하게 작동하며 리포스트, 댓글, 좋아요 등 다양한 상호작용이 가능합니다. 일반적인 게재 규칙이 적용되며 POST statuses/update로 생성됩니다.
• ‘프로모션 전용’ 트윗은 POST accounts/:account_id/tweet으로 생성할 수 있으며, 프로모션 트윗 캠페인에 사용할 수 있지만 팔로워에게 노출되거나 공개 타임라인에 표시되지는 않습니다. 특정 계정의 프로모션 전용 트윗 목록을 조회하려면 GET accounts/:account_id/scoped_timeline을 사용하세요.

​

프로모티드 계정

• 프로모티드 계정은 사용자가 아직 팔로우하지 않았지만 관심을 가질 만한 계정을 추천하는 Who to Follow 기능의 일부입니다. 프로모티드 계정은 사용자가 좋아할 수 있는 더 다양한 계정을 발견하도록 돕습니다.
• 타임라인용 프로모티드 계정은 프로모티드 트윗을 프로모티드 계정 캠페인과 연결해 사용자 타임라인에 표시합니다.

프로모티드 트렌드는 Ads API에서 제공되지 않습니다.

​

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

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

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

라인 아이템은 캠페인에서 정의된 예산을 소진합니다. 라인 아이템은 참여당 입찰가, 홍보할 게시물(Tweet) 또는 계정, 그리고 타기팅 규칙을 결합합니다.

​

분석

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

청구 지표의 경우 데이터는 이벤트 발생 후 최대 3일 뒤에야 확정될 수 있습니다. 그전까지 해당 데이터는 잠정치로 간주해야 합니다. 최종 청구 금액 산정 대상 수치는 항상 잠정치보다 작습니다. 청구 대상 수치는 스팸 및 관련 저품질 트래픽을 반영해 조정됩니다. 시간 관련 기타 고려 사항은 Timezones를 참조하세요.

​

캠페인 생성 - 단계별 안내

다음 예시는 twurl을 사용해 앱과 사용자를 설치, 구성, 인증했다는 가정하에 진행합니다. twurl은 cURL과 유사한 명령줄 도구로, X OAuth 인증을 안정적으로 처리합니다. twurl은 Ads API(및 REST API) 기능을 빠르게 테스트하고 디버깅하는 데 매우 유용합니다. 요청과 응답의 전체 헤더를 확인하려면 cURL의 -v 옵션과 대략 동일한 -t를 사용해 호출을 추적하세요.

이 예시에서는 키워드 타기팅이 적용된 Promoted Ads 캠페인을 생성합니다.

1. 계정 id를 조회합니다.

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

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

2. 자금 조달 수단 id를 조회합니다.

이전에 가져온 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": "첫 캠페인",
    "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": "첫 캠페인"
      "total_budget_amount_local_micro": 500000000
    }
  }
}

4. 캠페인에 연동된 라인 아이템을 생성합니다.

이제 캠페인 id가 있으므로, 해당 캠페인에 연동할 라인 아이템을 생성할 수 있습니다. 라인 아이템에는 입찰가, 타기팅, 그리고 캠페인의 실제 크리에이티브 요소가 포함됩니다. 이 라인 아이템에서는 $1.50의 입찰가로 트윗을 홍보합니다.

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

{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "제목 없음",
    "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": "샌프란시스코-오클랜드-산호세 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": "참여",
    "product_type": "프로모션된 트윗",
    "bid_unit": "참여",
    "total_budget_amount_local_micro": null,
    "objective": "참여",
    "id": "yyyy",
    "entity_status": "활성",
    "optimization": "기본",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "긍정만",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "활성"
      "account_id": "xxxxxx"
    }
  }
}

이것으로 완료되었습니다! 이제 타임라인에서 집행 중인 활성화·타게팅·예산 설정이 완료된 Promoted Tweets 캠페인이 실행되고 있습니다.

​

목표 기반 캠페인

목표 기반 캠페인과 가격 책정은 광고주가 마케팅 목표에 부합하는 행동에 대해서만 비용을 지불할 수 있도록 합니다. 이를 위해 라인 아이템에 적절한 objective를 설정하세요.

라인 아이템 쓰기 엔드포인트에서 사용되고 읽기 엔드포인트에서 반환되는 파라미터는 objective입니다. 이 필드는 현재 다음 값을 가집니다:

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

목표는 경매에서의 캠페인 최적화 방식과 과금 방식에 영향을 줍니다. 예를 들어 APP_ENGAGEMENTS에는 CPAC, APP_INSTALLS에는 CPAC 또는 CPI, WEBSITE_CLICKS에는 CPLC, FOLLOWERS에는 CPF, ENGAGEMENTS에는 CPE, REACH에는 CPM 등 목표별 가격 책정을 제공합니다.

모바일 앱 프로모션 캠페인에는 APP_ENGAGEMENTS 또는 APP_INSTALLS 목표가 반드시 포함되어야 합니다.

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

캠페인 목표	API objective	트윗 내 미디어	가격 모델
앱 재참여	APP_ENGAGEMENTS	이미지 또는 동영상 앱 다운로드 카드 필수.	CPAC
앱 설치	APP_INSTALLS	이미지 또는 동영상 앱 다운로드 카드 필수.	CPAC 또는 CPI (charge_by로 설정)
도달	REACH	제한 없음.	CPM
팔로워	FOLLOWERS	트윗은 필수는 아니지만 권장됩니다. 팔로워 캠페인의 트윗에는 미디어 제한이 없으나, 텍스트 전용 트윗을 권장합니다. 자세한 정보	CPF
참여	ENGAGEMENTS	제한 없음.	CPE
동영상 조회	VIDEO_VIEWS	동영상 대화 카드, 동영상 또는 GIF 필수.	CPV 또는 3초/100% 조회 기준 비용
프리롤 조회	PREROLL_VIEWS	동영상 필수.	CPV 또는 3초/100% 조회 기준 비용
웹사이트 클릭	WEBSITE_CLICKS	웹사이트 카드를 권장하지만 필수는 아닙니다. 트윗에는 웹사이트 카드 또는 웹사이트 링크 중 하나만 포함되어야 합니다(둘 다는 불가).	CPLC

​

자금 조달 수단

자금 조달 수단은 캠페인 예산의 원천입니다. 자금 조달 수단은 Ads API로 생성할 수 없으며, 사용하려면 X의 광고주 계정 관리자(신용 한도) 또는 ads.x.com(신용카드)을 통해 미리 설정되어 있어야 합니다.

계정의 모든 funding_instruments 목록을 가져오려면 GET accounts/:account_id/funding_instruments를, 특정 항목의 세부 정보는 GET accounts/:account_id/funding_instruments/:funding_instrument_id를 참조하세요.

​

자금 조달 수단 속성

설명: account_id, 자금 조달 수단 id, 자금 조달 수단 type, description, 그리고 io_header(인서션 오더 헤더 ID). 하나의 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으로 인코딩됩니다. “정수 값”을 표현하려면 모든 통화에서 로컬 마이크로 값에 1e6(1_000_000)을 곱해야 합니다.

​

속성 세부정보

credit_limit_local_micro는 CREDIT_CARD 또는 CREDIT_LINE 유형의 자금 조달 수단에만 유효하며, 해당 수단의 신용한도를 나타냅니다.

funded_amount_local_micro는 INSERTION_ORDER 유형의 자금 조달 수단에만 유효하며, 배정 예산을 나타냅니다.

credit_remaining_local_micro는 CREDIT_LINE 및 AGENCY_CREDIT_LINE 유형의 자금 조달 수단에 유효합니다. 이는 해당 자금 조달 수단에서 이미 지출된 금액을 credit_limit_local_micro에서 뺀 값을 의미합니다. 이는 funded_amount_local_micro와 지출 금액의 차이를 의미하지 않습니다. 신용한도와 배정 금액은 광고주와의 서로 다른 기초 자금 조달 방식과 지출 약정을 반영하므로 구분합니다.

​

자금 조달 수단의 종류

신용카드

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

신용 한도

삽입 지시서(IO) 형태로 제공되며, 계정 매니저가 설정합니다.

멀티 핸들 신용 한도

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

예를 들어 @NikeSB와 @NikeFuel은 모두 @Nike 신용 한도에 접근할 수 있습니다. 이 자금 조달 수단은 다른 수단과 동일하게 제공됩니다. funding_instrument 엔드포인트에 GET 요청을 보내 데이터를 조회하세요. 다음은 예시 응답입니다(‘CREDIT_LINE’ 유형에 주목).

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

{
    "request": {
        "params": {
            "account_id": "a0b1c3"
        }
    },
    "data": [
        {
            "start_time": "2013-05-30T04:00:00Z",
            "description": "FakeNike - 신용한도",
            "credit_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
}

이 자금 조달 수단의 특이한 점은 유형과, 이 수단과 연결된 모든 계정에서 사용할 수 있다는 사실뿐입니다. 물론 이 수단으로 자금이 지원되는 캠페인은 이를 공유하는 모든 계정 전반에서 남은 크레딧에 영향을 미칩니다. 특정 신용한도와 연결된 계정의 세부 정보는 API(및 ads.x.com)에서도 제공되지 않습니다.

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

​

타기팅

타기팅은 Ads API의 핵심 개념입니다. 타기팅은 라인 아이템 단위로 설정되며, 옵션은 게재 위치에 따라 달라집니다. 새로운 타기팅 기준을 설정하려면 POST accounts/:account_id/targeting_criteria를 사용하고, 기존 기준을 업데이트하려면 PUT accounts/:account_id/targeting_criteria를 사용하세요.

모든 라인 아이템 목록을 가져오려면 GET accounts/:account_id/line_items를, 특정 라인 아이템을 조회하려면 GET accounts/:account_id/line_items/:line_item_id를 사용하세요.

​

게재 위치별 타기팅 옵션

Promoted Tweets 및 Promoted Accounts 제품은 다양한 게재 위치에서 활용할 수 있습니다. Promoted Trends(PTr)는 API로 제공되지 않습니다.

가능한 게재 위치 조합은 GET line_items/placements 엔드포인트를 참고하세요. 각 게재 위치마다 타기팅 옵션이 다릅니다. 위치, 플랫폼, 성별은 모든 게재 위치에서 사용 가능합니다. 그 외 옵션은 게재 위치 유형의 맥락에 따라 달라집니다.

• X Search: 연령 타기팅, 기기, 이벤트, 성별, 키워드 유형(전체), 언어, 위치, 네트워크 활성화, 이동통신사, 플랫폼, 플랫폼 버전, 맞춤형 오디언스, Wi‑Fi 전용
• X Timeline: 연령 타기팅, 기기, 이벤트, 팔로워의 팔로워, 유사 팔로워, 성별, 관심사, 언어, 위치, 네트워크 활성화, 이동통신사, 비정확 일치 키워드 유형, 파트너 오디언스 유형, 플랫폼, 플랫폼 버전, 리타기팅 유형, 맞춤형 오디언스, TV 타기팅 유형, Wi‑Fi 전용
• X Profiles & Tweet Details: 연령 타기팅, 기기, 이벤트, 팔로워의 팔로워, 유사 팔로워, 성별, 관심사, 언어, 위치, 네트워크 활성화, 이동통신사, 비정확 일치 키워드 유형, 파트너 오디언스 유형, 플랫폼, 플랫폼 버전, 리타기팅 유형, 맞춤형 오디언스, TV 타기팅 유형, Wi‑Fi 전용

​

타기팅 유형 이해하기

연령 타기팅: 특정 연령 구간을 기준으로 사용자를 타기팅합니다. 연령 구간 enum 목록은 열거형 페이지에서 확인할 수 있습니다.

이벤트: 타기팅할 이벤트를 지정합니다. 타기팅에는 한 번에 하나의 이벤트만 사용할 수 있습니다(라인 아이템별). 타기팅에 사용할 수 있는 이벤트는 GET targeting_criteria/events 엔드포인트에서 확인하세요.

성별: 남성(1) 또는 여성(2)을 타기팅합니다. 모두를 타기팅하려면 null로 두세요.

설치된 앱 스토어 카테고리: 사용자가 설치했거나 관심을 보인 앱 카테고리를 기반으로 타기팅할 때 이 유형을 사용합니다. GET targeting_criteria/app_store_categories를 참조하세요.

관심사: 관심사로 사용자를 타기팅합니다. 관심사 목록은 GET targeting_criteria/interests에서 가져오세요. 최대 100개의 관심사를 타기팅할 수 있습니다.

팔로워의 팔로워: 현재 계정에서 완전히 프로모션 가능한 사용자의 팔로워를 타기팅합니다(참고: 현재는 기본 계정 보유자만 해당 계정의 완전히 프로모션 가능한 사용자입니다). 프로모션 가능한 사용자 목록은 GET accounts/:account_id/promotable_users로 가져올 수 있습니다.

팔로워와 유사한 사용자: 특정 사용자의 팔로워와 동일한 관심사를 가진 사람들을 타기팅합니다. 최대 100명의 Users를 사용할 수 있습니다.

위치: 타기팅할 위치를 최대 2,000개까지 지정합니다. 목록은 GET targeting_criteria/locations에서 가져오세요. 특정 국가를 타기팅하는 광고에는 추가 요구 사항이 있습니다. 자세한 내용은 국가 타기팅 및 게재 요구 사항을 참조하세요.

키워드: 키워드 타기팅 옵션은 게재 위치 유형에 따라 달라집니다. 타기팅에 키워드를 최대 1,000개까지 사용할 수 있습니다(라인 아이템별). 옵션은 키워드 유형 섹션을 참조하세요.

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

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

새 모바일 기기 타기팅: 사용자가 해당 기기로 처음 X에 접속한 날짜를 기준으로 도달합니다. 타기팅 유형 NETWORK_ACTIVATION_DURATION을 사용하고, operator_type으로 미만은 LT, 이상은 GTE를 사용합니다.

플랫폼, 플랫폼 버전, 디바이스, 및 WiFi 전용: 다양한 기준으로 모바일 디바이스를 타기팅할 수 있습니다. 플랫폼은 광범위한 휴대폰 범주를 포괄하는 상위 수준의 타기팅 유형입니다. 예시 값은 iOS 및 Android입니다. 디바이스를 사용하면 iPhone 5s, Nexus 4, Samsung Galaxy Note처럼 특정 모바일 디바이스 사용자를 타기팅할 수 있습니다. 플랫폼 버전을 사용하면 특정 모바일 운영체제의 버전별(포인트 릴리스까지) 사용자를 타기팅할 수 있습니다. 예로 iOS 7.1과 Android 4.4가 있습니다. WiFi 전용은 WiFi 네트워크를 사용하는 사용자만 타기팅합니다. 이 설정을 사용하지 않으면 통신사 연결과 WiFi를 모두 사용하는 사용자도 타기팅됩니다.

• 플랫폼과 디바이스에 겹침이 없으면 동시에 타기팅할 수 있습니다. 예: 플랫폼으로 Blackberry, 디바이스로 iPad Air를 동시에 타기팅할 수 있습니다.
• 디바이스와 OS 버전은 동시에 타기팅할 수 있습니다. 예: iPad Air와 iOS >= 7.0을 타기팅할 수 있습니다.
• 디바이스보다 더 광범위한 플랫폼은 함께 타기팅할 수 없습니다. 예: iOS와 iPad Air를 함께 타기팅할 수 없습니다.

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

TV Targeting

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

Tweet Engager Retargeting

Tweet engager 리타겟팅은 광고주가 X에서 프로모션 또는 오가닉 Tweet에 노출되었거나 상호작용한 사용자들을 기기 전반에서 타겟팅할 수 있도록 합니다. 이를 통해 광고주는 X에서 광고주의 콘텐츠를 보았거나 상호작용한 사람들에게 후속 메시지나 오퍼로 다시 도달해 추가 상호작용 또는 전환 가능성이 높은 대상을 공략할 수 있습니다. 사용자는 노출 또는 상호작용 후 수분 내 타겟팅 대상이 되며, 상호작용은 최대 90일, 노출은 최대 30일 동안 자격이 유지됩니다.

Tweet Engager 타겟팅 유형:

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

Note: ENGAGEMENT_TYPE은 하나 이상의 유효한 CAMPAIGN_ENGAGEMENT 또는 USER_ENGAGEMENT 값과 함께 필수입니다. 두 가지 tweet engager 타겟팅 유형을 모두 사용할 수 있으며, 하나의 라인 아이템에서 여러 캠페인을 타겟팅할 수 있습니다.

Video Viewer Targeting: Video viewer 타겟팅은 Tweet engager 타겟팅을 확장하여, X에서 동영상의 일부 또는 전부를 시청한 오디언스를 타겟팅할 수 있도록 합니다. 광고주는 오가닉 동영상, 프로모션 동영상, 또는 둘 다를 타겟팅할 수 있습니다. 프로모션 동영상은 동영상 조회 목표 캠페인이나 라인 아이템으로만 제한되지 않습니다.

Video Viewer 타겟팅 유형:

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

Tweet engager 타겟팅과 마찬가지로, ENGAGEMENT_TYPE을 사용하는 경우 라인 아이템의 타겟팅 기준에 다음 중 하나 이상이 함께 포함되어야 합니다:

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

Keyword Types

개념적 개요는 keyword targeting 지원 문서를 참조하세요.

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

Emoji targeting

이모지 타기팅은 키워드 타기팅을 통해 지원됩니다. 이모지 타기팅을 사용하려면 해당 이모지를 나타내는 유니코드 코드포인트(예: ‘얼굴에 기쁨의 눈물’ 이모지(😂)의 경우 UTF-8 기준 xF0x9Fx98x82, 코드포인트는 U+1F602)에 대해 키워드 타기팅을 생성하면 됩니다. 지원되는 이모지는 twemoji 목록에서 확인할 수 있습니다. 특정 이모지를 타기팅하면 해당 이모지의 모든 변형이 함께 타기팅됩니다.

필수/선택 여부 및 각 항목의 세부 정보를 요약한 내용은 PUT accounts/:account_id/targeting_criteria를 참조하세요.

​

타기팅 기준 조합

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

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

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

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

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

예시

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

지리 타기팅 예시:

캠페인의 광고 그룹이 다음과 같이 타기팅한다고 가정해 봅시다.

• 미국, 영국, 캐나다의 X 사용자(위치)
• 여성(성별)
• 맞춤 고객 목록 기반(“Primary”)
• 키워드 포함(“Primary”)

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

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

​

추가 예시

• 성별과 지역을 선택하고 기본(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)

​

예산 페이싱

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

표준 게재를 끄면 타게팅과 경쟁 상황에 따라 하루 초반에라도 일일 예산이 소진될 때까지 가능한 한 빠르게 노출을 제공하고 참여를 유도합니다. 이를 가속 게재라고 합니다.

시작하기

표준 게재는 모든 캠페인에 기본으로 설정되어 있으므로 끌 의사가 없다면 별도 조치가 필요하지 않습니다. 캠페인의 일일 예산을 최대한 빠르게 집행하려면 standard_delivery 매개변수를 false로 설정하여 가속 게재로 전환하세요(참고: GET accounts/:account_id/campaigns).

참고 사항

• “하루(Day)”는 X 광고주 계정 시간대(예: America/Los_Angeles)를 기준으로 합니다.
• 초기 결과에 따르면 표준 게재는 하루 전반에 걸쳐 더 일관된 커버리지를 제공하며, 광고주의 eCPE/CPF 개선에 도움이 됩니다.

예산 및 페이싱에 대한 자세한 내용은 입찰 및 경매 FAQ를 참고하세요.

​

타겟팅 입찰

캠페인 관리

​

입찰 전략

캠페인 생성 워크플로를 단순화하고 여러 매개변수 조합에서 발생하는 혼란을 줄이기 위해 입찰 전략 개념을 도입했습니다.

이전에 사용되던(레거시로 표시됨) 매개변수 조합은 동등한 goal 매개변수를 설정하여 모두 구현할 수 있습니다. 자세한 내용은 공지사항을 여기에서 확인하세요.

예시:

캠페인 목표	레거시	Ads API v10+
앱 설치	bid_type = AUTO bid_unit = APP_INSTALLS charge_by = APP_CLICKS	goal = APP_INSTALLS bid_strategy = AUTO
웹사이트 클릭	bid_type = TARGET (참고: 일부 캠페인 목표에서는 bid_unit가 필요하지 않음)	bid_strategy = TARGET

​

타겟 입찰

타겟 입찰을 사용하면 지불을 원하는 목표 비용을 지정할 수 있으며, X Ads 플랫폼은 해당 목표 비용에 근접하거나 그 이하를 유지하면서 성과 중심으로 캠페인을 최적화합니다.

이 기능은 비용을 통제하면서 원하는 행동(예: 링크 클릭, 잠재고객 확보, 팔로우)을 할 가능성이 높은 사용자에게 효과적으로 도달할 수 있는 유연성을 제공합니다. 캠페인 설정과 최적화(입찰 옵션 포함)에 더 다양한 선택지를 원하는 광고주에게 매우 유용한 기능입니다.

호환되는 캠페인 목표를 사용하는 라인 아이템의 경우, 지불 목표 비용을 지정할 수 있는 새로운 입찰가 책정 메커니즘을 도입했습니다. 당사 광고 플랫폼은 지정한 목표의 평균 비용을 설정값의 20% 이내로 유지하도록 노력하면서 더 많은 성과를 달성할 수 있도록 동적으로 대리 입찰합니다. 라인 아이템의 bid_strategy 설정을 TARGET 값으로 지정하면 다음과 같은 관련 캠페인 목표에서 타겟 입찰을 활성화할 수 있습니다:

• WEBSITE_CLICKS
• WEBSITE_CONVERSIONS 
• APP_INSTALLS 
• APP_ENGAGEMENTS
• REACH

​

국가 타기팅 및 노출 요건

캠페인 관리

국가별 타기팅 및 노출 요건은 이 페이지에 안내되어 있습니다. 모든 파트너는 해당 요건을 준수해야 합니다.

​

러시아

X의 광고 정책은 러시아어가 아닌 언어의 광고로 러시아를 타게팅하는 행위를 광고주에게 금지합니다. 사용자가 러시아를 명시적으로 타게팅하는 경우 다음 경고 메시지를 표시해야 합니다:

러시아를 타게팅하는 광고는 반드시 러시아어로 작성되어야 합니다.

​

파트너 관리 결제 수단

온보딩 흐름은 X 계정용 ads.x.com 계정을 설정하며, 해당 계정은 파트너가 Ads API로 관리하고 광고 지출은 파트너에게 청구됩니다.  

​

파트너 초기 설정

새 PMFI Ads API 파트너의 초기 설정 절차는 필요한 정보를 교환한 시점부터 최대 3주가 소요됩니다. 프로세스를 시작하려면 다음 정보를 X의 기술 담당자와 파트너 통합을 담당하는 X 담당자에게 공유해야 합니다:

• 파트너는 PGP/GPG 공개 키를 제공해야 합니다. Ads API 파트너와 X 간에는 공유 비밀 키를 교환해야 합니다. 이는 온보딩 과정에서 데이터를 검증하는 데 사용됩니다.
• Ads API 액세스에 사용할 X 앱의 app_id 또는 consumer_secret. developer.x.com에서 X 계정으로 로그인되어 있다면 앱 대시보드에서 기존 X 앱을 확인하고 수정할 수 있습니다. 새 X 앱을 만들어야 하는 경우 승인된 개발자 계정이 필요합니다. X는 프로덕션+샌드박스 용 앱 1개와 샌드박스 전용(선택 사항) 앱 1개를 허용합니다. 해당 X 앱은 기업의 파트너가 관리하는 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 권한 부여 프로세스가 포함됩니다.  

​

온보딩 리디렉트 페이로드

리디렉트용 URL:

https://ads.x.com/link_managed_account

리디렉트 URL은 다음 매개변수와 함께 호출됩니다:

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

​

콜백 URL 페이로드

기본 리디렉트 URL은 계정 연결 요청의 callback_url 매개변수를 통해 제공됩니다(위 참조). ads.x.com에서 추가하는 매개변수는 다음과 같습니다:

Name	Type	Description
status	string	OK 새 계정이 생성되었거나 기존의 적격 계정이 확인됨. ACCOUNT_INELIGIBLE 파트너별 제한 조건을 충족하지 않음 USER_MISMATCH ads.x.com에 로그인한 X 계정이 계정 연결 요청의 promotable_user_id 와 다름 INCOMPLETE_SERVING_BILLING_INFO 표준 시간대, 통화 또는 국가가 지정되지 않음 INVALID_COUNTRY 잘못된 국가 값이 제공됨 INVALID_CURRENCY 잘못된 통화 값이 제공됨 INVALID_TIMEZONE 잘못된 표준 시간대 값이 제공됨
account_id	URL 인코딩된 string	연결된 계정의 X Ads 계정 id
funding_instrument_id	URL 인코딩된 string	활성 파트너 관리 결제 수단의 ID
signature	아래에 설명된 대로 URL 인코딩 및 base64 인코딩된 이진 코드	공유 시크릿과 다른 매개변수를 결합해 호출의 진위와 매개변수의 유효성을 검증하는 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(위의 promotable_user_id = 1) 1을 키로 결합해 “secret&1”로 서명합니다.

결과는 Base64로 인코딩되며, 마지막 “\n” 없이 표시됩니다(단계 2 및 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=

이 서명은 이후 서명 매개변수에 원래 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 플로우를 시작하여 액세스 토큰을 발급받을 수 있습니다.  

​

리디렉션 불가 오류 플로우

account link URL이 잘못된 매개변수로 호출되면, 사용자는 유효하지 않거나 만료된 매개변수가 제공된 경우 OAuth 플로우에서 표시되는 페이지와 유사한 페이지를 보게 됩니다.  

​

PMFI의 지속 업데이트

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

​

게재 위치

X 광고는 여러 위치에 표시될 수 있습니다. 이는 placements 매개변수를 사용해 라인 아이템에서 설정합니다. 가능한 값은 다음과 같습니다:

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

라인 아이템의 product_type과 objective에 따라 허용되는 게재 위치가 결정됩니다. 각 제품 유형별로 유효한 게재 옵션을 조회하려면 GET line_items/placements 엔드포인트를 사용할 수 있습니다.

또한, 아래 표에는 유효한 게재 위치와 목표의 조합이 나열되어 있습니다.

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

참고: TWITTER_PROFILE 게재 위치만 지정하는 것은 불가능합니다.

참고: TWITTER_SEARCH에는 키워드 타기팅이 필요합니다.

참고: REACH 목표에는 반드시 TWITTER_TIMELINE 게재 위치가 포함되어야 합니다. ALL_ON_TWITTER, TWITTER_TIMELINE을 포함하는 임의의 게재 위치 조합, 또는 TWITTER_TIMELINE 단독으로 설정할 수 있습니다.

​

광고 그룹 FAQ

이 문서는 X의 Ads API에서 광고 그룹과 관련해 자주 묻는 질문을 모아 놓은 자료입니다.

​

광고 그룹이란 무엇인가요?

광고 그룹은 Ads API에서 라인 아이템(line item)으로 불리며, 캠페인 하위에 속해 특정 X 사용자 집합을 대상으로 타기팅 및 입찰에 사용됩니다. 광고주는 라인 아이템에 연동하여 트윗이나 미디어(예: 인스트림 광고로 프로모션되는 동영상)를 홍보합니다.

​

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

Ad Group는 동일한 캠페인 ID에 대해 POST accounts/:account_id/line_items를 여러 번 호출하고, 각 라인 아이템에 서로 다른 타기팅과 게시물(Tweets)을 연결해 생성합니다. 캠페인당 라인 아이템은 최대 100개, 단일 광고 계정의 활성 캠페인은 최대 200개까지 가능합니다. 모든 캠페인을 합산하면, 광고 계정당 활성 라인 아이템은 최대 8,000개로 제한됩니다.

​

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

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

Ad Groups의 장점은 입찰가, 예산, 크리에이티브, 타게팅 전반에 걸친 다양한 전략을 비교·관리할 수 있다는 점입니다. 여러 Promoted Tweet을 하나의 라인 아이템에 연결하면 경매는 그 그룹에서 가장 성과가 좋은 Tweet을 먼저 선택하고, 이어서 모든 라인 아이템 중 해당 캠페인에 가장 적합한 Tweet을 선택합니다. 단일 Tweet으로 구성된 Ad Group이 여러 개라면, 각 Ad Group에서 성과가 더 좋을 것으로 예상되는 Tweet을 사실상 선택하게 됩니다.

Ad Groups를 사용하면 광고주는 타게팅과 입찰을 훨씬 더 많은 조합으로 세분화할 수 있으며, 일반적으로 타게팅을 논리적 그룹으로 나눌 수 있습니다.

특히 Ads API 도구는 수많은 라인 아이템과 크리에이티브 조합으로 인해 수동 편집만으로는 어려운, Ad Groups 기반의 정교한 최적화 규칙을 중심으로 구축될 수 있습니다.

​

Ad Groups 캠페인에서 라인 아이템 예산은 캠페인 예산과 어떻게 연관되나요?

라인 아이템의 total_budget_amount_local_micro는 상위 캠페인의 총 예산을 초과할 수 없습니다. 마찬가지로 라인 아이템의 bid_amount_local_micro 값은 상위 캠페인의 daily_budget_amount_local_micro 또는 total_budget_amount_local_micro를 초과해서는 안 됩니다. 이러한 값을 잘못 설정하면 전체 캠페인이 일시 중지되고 송출 불가 상태가 될 수 있습니다.

캠페인의 총 예산은 하위 라인 아이템 예산의 합보다 적을 수 있으며, 라인 아이템 간 예산 배분은 부분적으로 Ads API 도구가 일일 성과에 맞춰 효과적으로 최적화하고 조정합니다. 이는 X의 실시간 특성으로 인해 타기팅(라인 아이템)의 일일 성과가 날마다 크게 달라질 수 있기 때문입니다.

​

광고 그룹이 단일 라인 아이템보다 더 나은 성과를 내나요?

캠페인 성과에는 다양한 요인이 영향을 미치며, 궁극적으로는 트윗이 성과를 좌우하는 최종 요소입니다. 라인 아이템은 해당 트윗이 사용자에게 게재 대상에 오를 수 있는지 여부를 결정하는 요소로 간주됩니다.

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

​

안내서

​

동영상 조회 프리롤 목표

다음 가이드는 Ads API에서 PREROLL_VIEWS 캠페인을 설정하는 데 필요한 절차를 설명합니다. 일반적으로 이러한 캠페인은 큐레이티드 카테고리와 콘텐츠 카테고리(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 Overview에서 확인하세요.

​

광고 계정에 동영상 추가

STATUS 명령으로 반환된 상태가 succeeded가 되면, 해당 엔드포인트에서 반환된 media_key를 사용해 POST accounts/:account_id/media_library 엔드포인트로 광고주의 미디어 라이브러리에 동영상을 추가합니다.

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

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

​

캠페인 설정하기

​

캠페인 생성

캠페인과 라인 아이템/광고 그룹을 생성하세요. 라인 아이템의 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
  }
}

​

라인 아이템 생성

라인 아이템의 categories 파라미터는 GET content_categories 엔드포인트를 통해 조회한 적절한 IAB 카테고리 세트로 설정되어야 합니다. 각 콘텐츠 카테고리는 하나 이상의 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": "큐레이팅-카테고리-라인-아이템",
      "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": "큐레이팅-카테고리-라인-아이템",
    "placements": \[
      "ALL\_ON\_TWITTER",
    \],
    "start_time": null,
    "bid\_amount\_local_micro": 5500000,
    "automatically\_select\_bid": false,
    "advertiser_domain": null,
    "target\_cpa\_local_micro": null,
    "raw_categories": \[
      "x",
      "5l",
      "9z"
    \],
    "primary\_web\_event_tag": null,
    "charge\_by": "VIEW\_3S_100PCT",
    "product\_type": "PROMOTED\_TWEETS",
    "end_time": null,
    "duration\_in\_days": null,
    "bid\_unit": "VIEW\_3S_100PCT",
    "total\_budget\_amount\_local\_micro": null,
    "objective": "PREROLL_VIEWS",
    "id": "iqwka",
    "entity_status": "ACTIVE",
    "automatic\_tweet\_promotion": null,
    "optimization": "DEFAULT",
    "frequency_cap": null,
    "android\_app\_store_identifier": null,
    "categories": \[
      "IAB3",
      "IAB13",
      "IAB21"
    \],
    "currency": "USD",
    "created_at": "2021-02-09T00:00:46Z",
    "tracking_tags": \[\],
    "ios\_app\_store_identifier": null,
    "amplify_config": {
      "auto_promote": true,
      "is_open": true
    },
    "updated_at": "2021-02-09T00:00:46Z",
    "campaign_id": "f2rp3",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

​

퍼블리셔 선택

광고주는 아래에 설명된 추가 세부 사항을 참고하여 콘텐츠 카테고리 또는 큐레이션 카테고리 중 하나를 타깃팅할 수 있습니다. 

참고: 라인 아이템은 큐레이션 또는 콘텐츠 카테고리 중 하나만 타깃팅할 수 있으며, 둘 다 동시에는 불가능합니다. 

​

큐레이션된 카테고리

큐레이션된 카테고리는 광고주가 미리 정의된 퍼블리셔 그룹을 타겟팅할 수 있게 하며, GET curated_categories 엔드포인트로 조회할 수 있습니다. 이 카테고리는 국가별로 제공되므로, 카테고리의 country_code에 따라 라인 아이템이 해당 국가를 타겟팅해야 합니다.

이러한 카테고리를 사용하려면, 아래 단계를 기재된 순서대로 수행해야 합니다.

1. 라인 아이템은 큐레이션된 카테고리의 country_code에 따라 해당 국가를 타겟팅해야 합니다.
2. POST line_item_curated_categories 엔드포인트를 사용하여 라인 아이템을 특정 curated_category_id와 연결해야 합니다.

주의: 라인 아이템을 큐레이션된 카테고리와 연결하면 거부 목록에 추가할 수 있는 퍼블리셔 수가 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": "미국",
      "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": "미국",
      "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": "뉴스 & 시사",
      "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": "뉴스",
      "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": "사회",
      "raw_negated": false,
      "raw\_targeting\_value": "5y",
      "id": "saib9q",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB14",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB12",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB14",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    }
  \]
}

계정 미디어(동영상)를 라인 아이템에 연결

동영상을 광고 그룹에 연결하려면 POST accounts/:account_id/media_creatives 엔드포인트를 사용하세요.

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

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

​

CTA와 대상 URL 설정

X의 대부분의 다른 캠페인과 달리 VIDEO_VIEWS_PREROLL 목표는 프로모션 게시물(Promoted Tweets)이나 카드(Cards)를 사용하지 않습니다. 대신 동영상 크리에이티브는 광고 그룹(라인 아이템)에 연결되고, CTA 정보는 preroll_call_to_action 엔터티에 연결됩니다. POST accounts/:account_id/preroll_call_to_action 엔드포인트를 사용하면 버튼 CTA와 대상 URL을 구성할 수 있습니다.

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

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

​

타기팅 기준 설정

프리 롤 동영상 광고에 사용되는 타기팅 기준은 배치 타기팅 기준 엔드포인트 POST batch/accounts/:account_id/targeting_criteria에서만 사용할 수 있습니다.

광고가 특정 사용자 집합과 매칭되지 않도록 제외하려면 부정 타기팅으로 CONTENT_PUBLISHER_USER를 사용하세요. 제외할 핸들의 X user_id 또는 publisher_user_id를 제공하세요.

GET publishers 엔드포인트를 사용하면 콘텐츠 카테고리에서 제외할 user_id 목록을 조회할 수 있습니다. GET curated_categories 응답에 반환되는 publisher_user_id를 사용하면 큐레이션 카테고리에 대해서도 유사한 제외 목록을 조회할 수 있습니다.

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

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

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

​

캠페인 시작

캠페인을 시작할 준비가 되면 PUT accounts/:account_id/campaigns/:id을 사용해 일시 중지를 해제하세요.

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

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

​

분석

VIDEO_VIEWS_PREROLL 캠페인의 분석 데이터는 통계 엔드포인트를 통해 확인할 수 있습니다.

​

타임라인 키워드 타게팅

키워드 타게팅은 캠페인의 도달 범위를 확대하는 X의 Promoted Tweets 제품의 핵심 기능입니다. 타임라인 키워드 타게팅을 사용하면, 최근 Tweet에 포함된 키워드를 기반으로 X 사용자를 타겟팅할 수 있습니다. 예를 들어 광고주가 순서에 상관없는 키워드 조합 “plan + trip”을 타겟팅하고 있을 때, 캠페인 진행 중 한 사용자가 “I’m starting to plan my trip to Cabo, any suggestions?”라고 Tweet하면, 해당 사용자는 곧 그 광고주의 Promoted Tweet을 보게 될 수 있습니다.

​

어떻게 작동하나요?

요약: API 관점에서 이번 변경은 매우 간단합니다. 이제 타임라인의 프로모션 트윗에 키워드 타기팅을 적용할 수 있습니다. 라인 아이템의 targeting_type을 unordered_keywords 또는 phrase_keywords로 설정하세요.

​

빠른 시작 가이드

• 배치를 ALL_ON_TWITTER 또는 TWITTER_TIMELINE으로 설정해 새 라인 아이템을 생성합니다. POST accounts/:account_id/line_items
• 방금 만든 라인 아이템에 대해 타기팅 기준을 BROAD_KEYWORD로 생성하고 키워드 값을 설정합니다. POST accounts/:account_id/targeting_criteria
• 다음 엔드포인트로 키워드를 업데이트할 수 있습니다: PUT accounts/:account_id/targeting_criteria
• 캠페인이 실행되면 라인 아이템의 성과를 평가할 수 있도록 통계를 가져옵니다. 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	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	name으로 리소스를 범위 지정하기 위한 선택적 쿼리입니다. Note: 대소문자를 구분하지 않는 접두 일치를 수행합니다. Type: string Min, Max length: 1, 255
sort_by optional	지원되는 속성을 기준으로 오름차순 또는 내림차순으로 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 상호 배타적입니다. Note: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

​

예제 요청

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

예시 응답

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

​

GET accounts/:account_id

인증된 사용자가 접근 권한을 가진 특정 계정을 조회합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
with_deleted 선택	삭제된 결과를 포함합니다. 유형: boolean 기본값: false 가능한 값: true, false

예시 요청

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

예시 응답

       {
         "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": "샌드박스 계정",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": null,
             "id": "gq12fh",
             "created_at": "2016-07-18T23:02:20Z",
             "updated_at": "2016-07-18T23:02:20Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

​

PUT accounts/:account_id

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

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
name optional	계정 이름입니다. Type: string Example: API McTestface
industry_type optional	계정이 속한 업종입니다. Type: string Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

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

Example Response

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

​

DELETE accounts/:account_id

참고: 샌드박스 전용

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

리소스 URL

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

매개변수

이름	설명
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예: 18ce54d4x5t

예시 요청

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

예시 응답

       {
         "data": {
           "name": "샌드박스 계정",
           "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"
           }
         }
       }

​

계정 앱

Postman에서 실행 ❯

​

GET account_apps

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

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연동되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	요청당 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
sort_by optional	지원되는 속성 기준으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
with_deleted optional	삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 상호 배타적입니다. Note: total_count를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200회로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

계정 내역

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	다음 결과 페이지를 가져오기 위한 커서입니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
entity_type required	데이터를 조회할 엔터티 유형입니다. Type: enum Example: PROMOTED_TWEET Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id required	데이터를 조회할 특정 엔터티의 id입니다. Type: string Example: 8u94t
start_time required	ISO 8601 형식으로 표현된 시작 시간으로 반환 데이터를 제한합니다. 참고: 반드시 정시(분 0, 초 0)로 표기해야 합니다. Type: string Example: 2017-05-19T07:00:00Z
end_time required	ISO 8601 형식으로 표현된 종료 시간으로 반환 데이터를 제한합니다. 참고: 반드시 정시(분 0, 초 0)로 표기해야 합니다. 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를 설정해야 합니다. 이는 이 엔드포인트를 통해 제공되는 해당 iab_categories 집합으로 line item 엔드포인트의 categories 요청 매개변수 값을 설정하여 수행할 수 있습니다.

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

Resource URL

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

Parameters

요청 매개변수 없음

Example Request

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

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Consumer Packaged Goods",
          "iab_categories": [
            "IAB9-26",
            "IAB9-18",
            "IAB9-29",
            "IAB9-1",
            "IAB9-8",
            "IAB9-22",
            "IAB6",
            "IAB9-5",
            "IAB9-12",
            "IAB9-11",
            "IAB9-23",
            "IAB9-14",
            "IAB4",
            "IAB9-25",
            "IAB9-17",
            "IAB23",
            "IAB9-24",
            "IAB9-13",
            "IAB16",
            "IAB9-4",
            "IAB9-9",
            "IAB9-20",
            "IAB22",
            "IAB9-28",
            "IAB9-27",
            "IAB9-16",
            "IAB9-31",
            "IAB9-3",
            "IAB9-19",
            "IAB10",
            "IAB9-2",
            "IAB9-6",
            "IAB9-21",
            "IAB9-10",
            "IAB9-15"
          ]
        },
        {
          "id": "1jm",
          "name": "건강 및 제약",
          "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 엔드포인트에서 확인할 수 있습니다. 요청은 Content-Type: application/json 헤더가 포함된 JSON 본문을 가진 HTTP POST여야 합니다.

참고: 최소 한 가지 기본 타겟팅 기준을 지정해야 합니다. 모든 기본 타겟팅 기준 목록은 캠페인 타겟팅 페이지에서 확인할 수 있습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
targeting_criteria required	타겟팅 기준 객체에 대한 모든 매개변수를 포함하는 JSON 객체입니다. 필수 및 선택 타겟팅 기준 매개변수 목록은 POST accounts/:account_id/targeting_criteria 엔드포인트에서 확인할 수 있습니다.
operator_type optional	타겟팅 기준 간의 관계를 지정합니다. 예를 들어, 부정 타겟팅을 설정하려면 operator_type=NE를 사용하세요. Type: enum Possible values: EQ, NE Default: EQ

예시 요청

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 권한은 인증된 사용자가 광고주를 대신해 널캐스트(또는 “Promoted-only”) 트윗을 작성할 수 있음을 의미합니다. 이는 ACCOUNT_ADMIN, AD_MANAGER, CREATIVE_MANAGER 액세스를 보유한 사용자에게만 제공됩니다.

Resource URL

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

Parameters

없음

Example Request

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

Example Response

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

​

입찰 규칙

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	쉼표로 구분된 식별자 목록을 지정해 특정 자금 조달 수단에 속한 캠페인으로만 응답을 제한합니다. 최대 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": "테스트",
          "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

현재 계정에 연동된 특정 캠페인을 조회합니다.

리소스 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
with_deleted optional	삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false

예시 요청

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

예시 응답

    {
      "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은 5,500,000으로 표시됩니다. 참고: total_budget_amount_local_micro보다 작거나 같아야 하며, 대부분의 자금 수단 유형에서 필수입니다. Type: long Example: 5500000
entity_status optional	캠페인 상태입니다. Type: enum Default: ACTIVE Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number optional	예약(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은 37,500,000으로 표시됩니다. 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 응답은 순서가 있는 항목 컬렉션을 반환합니다. 그 외에는 해당 단일 항목 엔드포인트와 구조가 동일합니다.

일괄 오류

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

리소스 URL

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

매개변수

Name	Description
operation_type required	항목별로 수행되는 작업 유형입니다. 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":"일괄 캠페인",
          "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은 5,500,000으로 표시됩니다. 값을 제공하지 않으면 캠페인은 총 예산과 캠페인 운영 기간에 따라 균등하게 집행됩니다. 참고: total_budget_amount_local_micro보다 작거나 같아야 합니다. Type: long Example: 5500000
entity_status optional	캠페인의 상태입니다. Type: enum Possible values: ACTIVE, PAUSED
name optional	캠페인 이름입니다. 최대 길이: 255자. Type: string Example: demo
purchase_order_number optional	예약 참조 번호입니다. 송장 대조를 돕기 위해 이 필드를 사용하세요. 최대 길이: 50자. Type: string Example: D00805843
standard_delivery optional	표준 또는 가속 게재를 사용합니다. 표준과 가속 게재에 대한 자세한 내용은 Budget Pacing을 참고하세요. budget_optimization이 CAMPAIGN으로 설정된 경우에만 사용 가능합니다. Type: boolean Default: true Possible values: true, false
total_budget_amount_local_micro optional	캠페인에 할당할 총 예산 금액입니다. 지정된 자금 조달 수단에 연결된 통화를 사용합니다. USD의 경우 $37.50은 37,500,000으로 표시됩니다. 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를 반환합니다.

Resource URL

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

Parameters

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

Example Request

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

Example Response

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

​

콘텐츠 범주

Postman에서 실행

​

GET content_categories

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

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

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

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

Resource URL

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

Parameters

요청 파라미터 없음

Example Request

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

Example Response

{
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "자동차 (승용차, 트럭, 레이싱)",
          "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 Categories 목록을 조회합니다.

각 curated_category는 응답의 country_codes에 명시된 특정 국가에서만 제공됩니다.

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

Resource URL

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

Parameters

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

Example Request

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

Example Response

{
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "농구",
          "description": "대학 팀, 프로 팀, 시즌 중 및 비시즌 농구 영상을 공유하는 주요 스포츠 미디어 계정을 포함한 최고의 일상 농구 콘텐츠 옆에 광고를 게재하세요.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20265254",
            "378174762",
            "900368808",
            "18939563",
            "18371803",
            "18360370",
            "770658432928079872",
            "11026952",
            "37085464",
            "16212685",
            "57422635",
            "281669945",
            "7117962",
            "23065057",
            "41688179",
            "29779226",
            "900280416",
            "364460082",
            "902030382",
            "19409270",
            "19077044",
            "18139461",
            "14992591",
            "66753565",
            "667563",
            "16727749",
            "40941404",
            "18481113",
            "791598918",
            "16201775",
            "15900167",
            "45891626",
            "191894553",
            "2181233851",
            "34352904",
            "171483987",
            "454122399",
            "57415242",
            "19263978",
            "902089998",
            "423540866",
            "2715223320",
            "22185437",
            "17292143",
            "55590247",
            "66757066",
            "22642626",
            "41604618",
            "87275465",
            "22643259",
            "32414973",
            "73406718",
            "20346956",
            "413422891",
            "45412765",
            "19537303",
            "459511725",
            "30954864",
            "21308488",
            "18552281",
            "19924520",
            "24903350",
            "851142163",
            "26270913",
            "20444254",
            "26074296",
            "6395222",
            "15537451",
            "28672101",
            "38053254",
            "24925573",
            "19564719",
            "18164425",
            "22815383",
            "20196159"
          ],
          "id": "929wbl6ymlfk",
          "created_at": "2019-11-08T21:12:47Z",
          "updated_at": "2021-03-09T20:36:44Z",
          "videos_monetized_in_last_thirty_days": 2446
        },
        {
          "name": "게이밍 인플루언서",
          "description": "온라인 게이밍에서 가장 유명하고 사랑받는 디지털 크리에이터들의 최고의 일상 게이밍 콘텐츠 옆에 광고를 게재하세요.",
          "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

이 광고 계정에 부여되어 접근 가능한 기능들의 컬렉션을 조회합니다. 기능은 설명적인 기능 키로 표시되며, 베타 또는 기타 제한적 릴리스로 도입되어 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	특정 기능 키를 조회할 수 있는 선택적 매개변수입니다. 요청에는 쉼표로 구분된 여러 키를 포함할 수 있습니다. 참고: 이 계정에서 접근 가능한 기능만 응답에 포함됩니다. 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 전용

Sandbox 계정에서 기능을 제거합니다.

최신 계정 기능 목록은 GET accounts/:account_id/features 엔드포인트를 통해 조회할 수 있습니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예: gq180y
feature_keys 필수	계정에서 제거할 계정 기능의 쉼표로 구분된 목록입니다. 유형: enum 가능한 값: 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

현재 계정에 연동된 일부 또는 모든 결제 수단의 세부 정보를 조회합니다.

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": "0650으로 끝나는 Visa",
          "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

현재 계정과 연결된 특정 자금 조달 수단을 조회합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
funding_instrument_id 필수	요청에서 사용 중인 자금 조달 수단을 가리키는 참조입니다. 유형: string 예시: lygyi
with_deleted 옵션	삭제된 결과를 포함합니다. 유형: boolean 기본값: false 가능한 값: true, false

요청 예시

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

응답 예시

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "0650으로 끝나는 Visa 카드",
        "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

샌드박스 전용

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

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

리소스 URL

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

매개변수

이름	설명
account_id 필수	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: gq1844
currency 필수	ISO-4217 형식의 통화입니다. 유형: string 예시: USD
start_time 필수	자금조달 수단이 활성화되어 사용 가능해지는 날짜로, ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-05-19T07:00:00Z
type 필수	생성할 자금조달 수단의 유형입니다. 유형: enum 가능한 값: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time 상황에 따라 필수	자금조달 수단이 비활성화되는 날짜로, ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-05-26T07:00:00Z
credit_limit_local_micro 선택 사항	이 자금조달 수단에 대해 사용 가능한 총 신용한도입니다. 참고: 일부 자금조달 수단 유형에만 적용됩니다. 유형: long 예시: 37500000
funded_amount_local_micro 선택 사항	이 자금조달 수단에 할당된 총 예산 금액입니다. 참고: 일부 자금조달 수단 유형에만 적용됩니다. 유형: long 예시: 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": "(결제 수단이 아직 설정되지 않았습니다)",
        "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 전용

샌드박스 환경에서 자금 조달 수단을 삭제합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	레버리지 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예: gq1844
funding_instrument_id 필수	요청에서 대상으로 삼는 자금 조달 수단의 참조입니다. 유형: string 예: hxt82

요청 예시

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

응답 예시

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(결제 수단이 아직 설정되지 않았습니다)",
        "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)에서 사용할 수 있는 유효한 앱 categories를 요청합니다.

리소스 URL

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

매개변수

이름	설명
count 선택 사항	각 요청당 조회할 레코드 수를 지정합니다. 유형: int 기본값: 200 최소, 최대: 1, 1000
cursor 선택 사항	다음 페이지의 카테고리를 가져오기 위한 커서를 지정합니다. 자세한 내용은 페이지 매김을 참조하세요. 유형: string 예시: gc-ddf4a
with_total_count 선택 사항	응답에 total_count 속성을 포함합니다. 참고: 이 매개변수와 cursor는 상호 배타적입니다. 참고: total_count를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다. 유형: boolean 기본값: false 가능한 값: true, false

요청 예시

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

응답 예시

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "예술 및 엔터테인먼트"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "도서 및 문학"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

​

라인 아이템(Line Items)

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

매개변수

이름	설명
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
line_item_id required	요청에서 대상으로 하는 라인 아이템의 참조입니다. 유형: string 예시: 8v7jo
with_deleted optional	삭제된 결과를 포함합니다. 유형: boolean 기본값: false 가능한 값: 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 제품 유형을 사용할 때 line_item에 트윗을 연결하면 표준 PROMOTED_ACCOUNT 게재 위치에 더해 모바일 타임라인 게재가 추가됩니다.

android_app_store_identifier 또는 ios_app_store_identifier를 설정하면 홍보 중인 모바일 앱과 일치하는 라인 아이템의 타기팅 기준이 자동으로 추가됩니다. 예를 들어 ios_app_store_identifier를 전달하면 iOS에 대한 PLATFORM 타기팅 기준이 추가됩니다.

참고: 캠페인당 라인 아이템은 100개로 제한되며, 모든 캠페인 전체에서 활성 라인 아이템은 256개로 제한됩니다.

Resource URL

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

Parameters

이름	설명
account_id 필수	사용할 계정의 식별자입니다. 리소스 경로 내에 표시되며 일반적으로 GET accounts를 제외한 모든 광고주 API 요청에 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
campaign_id 필수	라인 아이템을 생성할 캠페인의 식별자입니다. 유형: string 예시: 8slvg
end_time 필수	라인 아이템의 게재가 중단될 시간으로, ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-10-05T00:00:00Z
objective 필수	이 라인 아이템의 캠페인 목표입니다. 유형: enum 가능한 값: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements 필수	이 라인 아이템이 표시될 게재 위치입니다. 쉼표로 구분된 게재 위치 값 목록을 지정하십시오. 유형: 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 필수	이 라인 아이템에 포함될 프로모션 제품의 유형입니다. 유형: enum 가능한 값: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time 필수	라인 아이템의 게재가 시작될 시간으로, ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-07-05T00:00:00Z
advertiser_domain 경우에 따라 필수	프로토콜 지정 없이 이 광고주의 웹사이트 도메인입니다. 참고: 라인 아이템의 게재 위치가 PUBLISHER_NETWORK로 설정된 경우 필수입니다. 유형: string 예시: x.com
android_app_store_identifier 경우에 따라 필수	프로모션 애플리케이션의 Google App Store 식별자입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS 목표는 android_app_store_identifier 또는 ios_app_store_identifier 중 하나 이상의 앱 스토어 식별자 설정이 필요합니다. 유형: string 예시: com.twitter.android
bid_amount_local_micro 경우에 따라 필수	이 라인 아이템과 연결될 입찰 금액입니다. 지정된 펀딩 수단과 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표현됩니다. 참고: bid_strategy가 MAX 또는 TARGET으로 설정된 경우 필수입니다. 참고: 0보다 큰 값만 허용됩니다. 유형: long 예시: 5500000
categories 경우에 따라 필수	이 광고주의 관련 IAB 카테고리입니다. GET iab_categories를 참조하십시오. 참고: 라인 아이템의 게재 위치가 PUBLISHER_NETWORK로 설정된 경우 필수입니다. 유형: string 예시: IAB3-1
ios_app_store_identifier 경우에 따라 필수	프로모션 애플리케이션의 Apple App Store 식별자 중 숫자 부분입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS 목표는 android_app_store_identifier 또는 ios_app_store_identifier 중 하나 이상의 앱 스토어 식별자 설정이 필요합니다. 유형: string 예시: 333903271
primary_web_event_tag 경우에 따라 필수	기본 웹 이벤트 태그의 식별자입니다. 이 라인 아이템과 관련된 캠페인의 참여를 보다 정확하게 추적할 수 있습니다. 참고: 라인 아이템의 목표가 WEBSITE_CONVERSIONS로 설정된 경우 필수입니다. 유형: string 예시: nvo4z
advertiser_user_id 선택 사항	PREROLL_VIEWS 광고를 프로모션하는 핸들의 X 사용자 식별자입니다. 특정 클라이언트 애플리케이션만 이 매개변수를 사용할 수 있습니다. 유형: string 예시: 312226591
audience_expansion 선택 사항	이미 타겟팅된 사용자와 유사한 사용자를 타겟팅하여 캠페인의 도달 범위를 확장하는 데 사용됩니다. 참고: 기본적으로 확장이 적용되지 않습니다. 유형: enum 가능한 값: BROAD, DEFINED, EXPANDED
bid_strategy 선택 사항	입찰 메커니즘입니다. AUTO는 일일 예산 및 캠페인 게재 기간을 기반으로 입찰을 자동으로 최적화합니다. MAX는 허용 가능한 최대 입찰가를 설정하며 목표가 REACH 또는 FOLLOWERS로 설정된 경우 사용할 수 없습니다. TARGET은 일일 입찰 평균을 지정된 bid_amount_local_micro의 20% 이내로 유지하려고 시도하며 목표가 REACH, FOLLOWERS 또는 WEBSITE_CLICKS로 설정된 경우 사용할 수 있습니다. 참고: AUTO로 설정된 경우 bid_amount_local_micro는 무시됩니다. 참고: 목표에 따라 기본값이 설정됩니다. 유형: enum 가능한 값: AUTO, MAX, TARGET
duration_in_days 선택 사항	frequency_cap이 달성되는 기간입니다. 유형: int 가능한 값: 1, 7, 30
entity_status 선택 사항	라인 아이템 상태입니다. 유형: enum 기본값: ACTIVE 가능한 값: ACTIVE, DRAFT, PAUSED
frequency_cap 선택 사항	사용자에게 광고가 전달될 수 있는 최대 횟수입니다. 참고: REACH, ENGAGEMENTS, VIDEO_VIEWS 및 PREROLL_VIEWS 목표에만 지원됩니다. 유형: int 예시: 5
goal 선택 사항	이 라인 아이템과 함께 사용할 최적화 설정입니다. APP_PURCHASES 옵션은 APP_INSTALL에 사용할 수 있습니다. APP_CLICKS 및 APP_INSTALLS 옵션은 APP_INSTALL 및 APP_ENGAGEMENTS 목표 모두에 사용할 수 있으며 지원되는 MACT 파트너 사용이 필요할 수 있습니다. SITE_VISITS 옵션은 WEBSITE_CLICKS 목표에만 사용할 수 있습니다. 참고: 목표에 따라 기본값이 설정됩니다. 유형: enum 가능한 값: APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name 선택 사항	라인 아이템의 이름입니다. 유형: string 예시: demo 최소, 최대 길이: 1, 255
pay_by 선택 사항	이 라인 아이템에 대해 과금할 단위입니다. 이 설정은 APP_INSTALLS 목표를 사용하는 라인 아이템에 대해서만 수정할 수 있습니다. 참고: 기본 pay_by는 캠페인 목표 및 라인 아이템의 입찰 단위에 따라 자동으로 설정됩니다. APP_INSTALLS 목표는 APP_CLICK 및 IMPRESSION 값을 모두 지원합니다. IMPRESSION이 기본값입니다. LINK_CLICKS 목표는 LINK_CLICK 및 IMPRESSION 값을 모두 지원합니다. IMPRESSION이 기본값이지만 bid_strategy에 TARGET을 설정할 때는 지원되지 않습니다. SITE_VISITS 목표는 IMPRESSION 값을 지원합니다. 유형: enum 가능한 값: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery 선택 사항	표준 또는 가속 게재를 활성화합니다. 표준 게재와 가속 게재에 대한 자세한 내용은 예산 페이싱을 참조하세요. 상위 캠페인의 budget_optimization이 LINE_ITEM으로 설정된 경우에만 사용할 수 있습니다 유형: boolean 기본값: true 가능한 값: true, false
total_budget_amount_local_micro 선택 사항	라인 아이템에 할당할 총 예산 금액입니다. 지정된 펀딩 인스트루먼트와 연결된 통화가 사용됩니다. USD의 경우 $37.50은 37500000으로 표시됩니다. 유형: long 예시: 37500000
daily_budget_amount_local_micro 경우에 따라 필수	캠페인에 할당할 일일 예산 금액입니다. 지정된 펀딩 인스트루먼트와 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표시됩니다. 제공되지 않은 경우 캠페인은 총 예산과 캠페인 게재 기간을 기준으로 균등하게 지출됩니다. 상위 캠페인의 budget_optimization이 LINE_ITEM으로 설정된 경우에만 사용할 수 있습니다 참고: 이 값은 total_budget_amount_local_micro보다 작거나 같아야 합니다. 유형: long 예시: 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

단일 요청으로 새로운 라인 아이템을 일괄 생성할 수 있습니다.

배치 요청

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

배치 응답

배치 API 응답은 순서가 보장된 아이템 컬렉션을 반환합니다. 그 외에는 해당 단일 아이템 엔드포인트와 구조가 동일합니다.

배치 오류

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

리소스 URL

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

매개변수

Name	Description
operation_type required	아이템별로 수행되는 작업 유형입니다. Type: enum Possible values: Create, Delete, Update
params required	라인 아이템 객체에 필요한 모든 매개변수를 포함하는 JSON 객체입니다. 필수 및 선택 매개변수 목록은 여기를 참고하세요.

예시 요청

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 required	사용할 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 광고주 API 요청에 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
line_item_id required	요청에서 작업 중인 라인 아이템에 대한 참조입니다. 유형: string 예시: 8v7jo
advertiser_domain optional	프로토콜 지정 없이 이 광고주의 웹사이트 도메인입니다. 참고: 라인 아이템의 게재위치가 PUBLISHER_NETWORK로 설정된 경우 필수입니다. 유형: string 예시: x.com
advertiser_user_id optional	PREROLL_VIEWS 광고를 홍보하는 핸들의 X 사용자 식별자입니다. 특정 클라이언트 애플리케이션만 이 매개변수를 사용할 수 있습니다. 유형: string 예시: 312226591
android_app_store_identifier optional	홍보할 애플리케이션의 Google App Store 식별자입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS 목표는 android_app_store_identifier 또는 ios_app_store_identifier 중 하나 이상의 앱 스토어 식별자 설정이 필요합니다. 유형: string 예시: com.twitter.android
audience_expansion optional	이미 타겟팅된 사용자와 유사한 사용자를 타겟팅하여 캠페인 도달 범위를 확장하는 데 사용됩니다. 유형: enum 가능한 값: BROAD, DEFINED, EXPANDED
bid_amount_local_micro optional	이 라인 아이템과 연결될 입찰 금액입니다. 지정된 펀딩 인스트루먼트와 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표시됩니다. 참고: bid_strategy가 MAX 또는 TARGET으로 설정된 경우 필수입니다. 참고: 0보다 큰 값만 허용됩니다. 유형: long 예시: 140000
bid_strategy optional	입찰 메커니즘입니다. AUTO는 일일 예산 및 캠페인 게재 기간을 기반으로 입찰을 자동으로 최적화합니다. MAX는 허용 가능한 최대 입찰가를 설정하며 목표가 REACH 또는 FOLLOWERS로 설정된 경우 사용할 수 없습니다. TARGET은 일일 입찰 평균을 지정된 bid_amount_local_micro의 20% 이내로 유지하려고 시도하며 목표가 REACH 또는 WEBSITE_CLICKS로 설정된 경우 사용할 수 있습니다. 참고: AUTO로 설정된 경우 bid_amount_local_micro는 무시됩니다. 참고: 목표에 따라 기본값이 설정됩니다. 유형: enum 가능한 값: AUTO, MAX, TARGET
categories optional	이 광고주와 관련된 IAB 카테고리입니다. GET iab_categories를 참조하십시오. 참고: 라인 아이템의 게재위치가 PUBLISHER_NETWORK로 설정된 경우 필수입니다. 유형: string 예시: IAB3-1
duration_in_days optional	frequency_cap이 달성되는 기간입니다. 유형: int 가능한 값: 1, 7, 30
entity_status optional	라인 아이템 상태입니다. 유형: enum 가능한 값: ACTIVE, PAUSED
end_time optional	라인 아이템이 게재를 중지할 시간으로 ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-10-05T00:00:00Z
frequency_cap optional	사용자에게 광고가 전달될 수 있는 최대 횟수입니다. 참고: REACH, ENGAGEMENTS, VIDEO_VIEWS 및 PREROLL_VIEWS 목표에만 지원됩니다. 유형: int 예시: 5
goal optional	이 라인 아이템과 함께 사용할 최적화 설정입니다. APP_PURCHASES 옵션은 APP_INSTALL에 사용할 수 있습니다. APP_CLICKS 및 APP_INSTALLS 옵션은 APP_INSTALL 및 APP_ENGAGEMENTS에 사용할 수 있으며 지원되는 MACT 파트너 사용이 필요할 수 있습니다. 참고: 목표에 따라 기본값이 설정됩니다. 유형: 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 optional	홍보할 애플리케이션의 Apple App Store 식별자 중 숫자 부분입니다. 참고: APP_INSTALLS 및 APP_ENGAGEMENTS 목표는 android_app_store_identifier 또는 ios_app_store_identifier 중 하나 이상의 앱 스토어 식별자 설정이 필요합니다. 유형: string 예시: 333903271
name optional	라인 아이템의 이름입니다. 유형: string 예시: demo
pay_by optional	이 라인 아이템에 청구할 단위입니다. 이 설정은 APP_INSTALLS 목표를 사용하는 라인 아이템에 대해서만 수정할 수 있습니다. 참고: 기본 pay_by는 캠페인 목표 및 라인 아이템의 입찰 단위에 따라 자동으로 설정됩니다. APP_INSTALLS 목표는 APP_CLICK 및 IMPRESSION 값을 모두 지원합니다. IMPRESSION이 기본값입니다. LINK_CLICKS 목표는 LINK_CLICK 및 IMPRESSION 값을 모두 지원합니다. IMPRESSION이 기본값이지만 bid_strategy에 TARGET을 설정할 때는 지원되지 않습니다. SITE_VISITS 목표는 IMPRESSION 값을 지원합니다. 유형: enum 가능한 값: APP_CLICK, IMPRESSION, LINK_CLICK
start_time optional	라인 아이템이 게재를 시작할 시간으로 ISO 8601 형식으로 표현됩니다. 유형: string 예시: 2017-07-05T00:00:00Z
total_budget_amount_local_micro optional	라인 아이템에 할당될 총 예산 금액입니다. 지정된 펀딩 인스트루먼트와 연결된 통화가 사용됩니다. USD의 경우 $37.50은 37500000으로 표시됩니다. 유형: long 예시: 37500000
daily_budget_amount_local_micro optional	캠페인에 할당될 일일 예산 금액입니다. 지정된 펀딩 인스트루먼트와 연결된 통화가 사용됩니다. USD의 경우 $5.50은 5500000으로 표시됩니다. 제공되지 않은 경우 캠페인은 총 예산 및 캠페인 게재 기간을 기반으로 균등하게 지출됩니다. 상위 캠페인의 budget_optimization이 LINE_ITEM으로 설정된 경우에만 사용할 수 있습니다. 참고: 이 값은 total_budget_amount_local_micro보다 작거나 같아야 합니다. 유형: long 예시: 5500000

요청 예시

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

응답 예시

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

​

DELETE accounts/:account_id/line_items/:line_item_id

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

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

참고: 라인 아이템을 삭제해도 하위 promoted_tweets는 요청에 with_deleted=true가 지정된 경우에 한해 GET accounts/:account_id/promoted_tweets 및 GET accounts/:account_id/promoted_tweets/:promoted_tweet_id 엔드포인트에서만 반환됩니다. 이러한 promoted_tweets는 실제로 삭제되지 않습니다(응답에서 "deleted": false). 연쇄 삭제는 수행되지 않습니다.

Resource URL

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

Parameters

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_id required	요청에서 대상이 되는 라인 아이템에 대한 참조입니다. Type: string Example: 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": "제목 없음",
        "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 Pre-roll Objective 가이드에서 확인할 수 있습니다.

​

GET accounts/:account_id/line_item_curated_categories

현재 계정에 연결된 라인 아이템 선별 카테고리의 세부 정보를 일부 또는 모두 조회합니다.

Resource URL

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

Parameters

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	각 요청에서 조회할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 페이지의 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참고하세요. Type: string Example: 8x7v00oow
sort_by optional	지원되는 속성 기준으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참고하세요. Type: string Example: created_at-asc
with_deleted optional	삭제된 결과를 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	응답에 total_count 속성을 포함합니다. Note: 이 매개변수와 cursor는 상호 배타적입니다. Note: total_count를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

현재 계정과 연관된 특정 Line Item Curated Category의 세부 정보를 조회합니다.

리소스 URL

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

매개변수

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

요청 예시

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

응답 예시

    {
      "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 객체를 연결합니다.

리소스 URL

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

매개변수

이름	설명
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
curated_category_id required	요청에서 사용 중인 curated category 엔티티에 대한 참조입니다. 유형: string 예시: 10miy
line_item_id required	요청에서 사용 중인 라인 아이템에 대한 참조입니다. 유형: string 예시: 8v7jo

예시 요청

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

예시 응답

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

지정된 라인 아이템 큐레이션 카테고리를 삭제합니다.

리소스 URL

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

매개변수

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연관되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_curated_category_id required	요청에서 대상으로 하는 라인 아이템 큐레이션 카테고리에 대한 참조입니다. Type: string Example: 1bzq3

예시 요청

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

예시 응답

    {
      "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	지정된 제품 유형에 대해 유효한 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

현재 계정과 연결된 일부 또는 모든 미디어 크리에이티브의 세부 정보를 조회합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
campaign_id 선택	지정된 캠페인과 연결된 미디어 크리에이티브만 반환하도록 응답 범위를 제한합니다. 유형: string 예시: 8gdx6
count 선택	각 요청당 조회를 시도할 레코드 수를 지정합니다. 유형: int 기본값: 200 최소, 최대: 1, 1000
cursor 선택	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. 유형: string 예시: 8x7v00oow
line_item_ids 선택	쉼표로 구분된 식별자 목록을 지정하여, 해당 라인 아이템과 연결된 미디어 크리에이티브만 반환하도록 응답 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 유형: string 예시: 8v7jo
media_creative_ids 선택	쉼표로 구분된 식별자 목록을 지정하여, 원하는 미디어 크리에이티브만 반환하도록 응답 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. 유형: string 예시: 1bzq3
sort_by 선택	지원되는 속성으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참조하세요. 유형: string 예시: created_at-asc
with_deleted 선택	삭제된 결과를 포함합니다. 유형: boolean 기본값: false 가능한 값: true, false
with_total_count 선택	total_count 응답 속성을 포함합니다. 참고: 이 매개변수와 cursor는 상호 배타적입니다. 참고: total_count를 포함하는 요청은 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다. 유형: boolean 기본값: false 가능한 값: true, false

예시 요청

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

예시 응답

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

현재 계정에 연결된 특정 미디어 크리에이티브의 세부 정보를 조회합니다.

리소스 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	이 요청에서 조회할 미디어 크리에이티브의 참조입니다. 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”)에서만 사용해야 합니다. preroll 에셋과 함께 사용하면 이 값은 무시됩니다. preroll 에셋에 URL을 연결하려면 POST accounts/:account_id/preroll_call_to_actions 엔드포인트를 사용하세요. 참고: 라인 아이템의 objective가 WEBSITE_CLICKS로 설정된 경우 필수입니다. Type: string Example: https://blog.x.com/

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/media_creatives/:media_creative_id

현재 계정에 속한 지정된 미디어 크리에이티브를 삭제합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
media_creative_id 필수	요청에서 대상으로 하는 미디어 크리에이티브에 대한 참조입니다. 유형: string 예시: 1bzq3

요청 예시

DELETE 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": "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

매개변수

이름	설명
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 응답 속성을 포함합니다. 참고: 이 매개변수와 cursor는 상호 배타적입니다. 참고: 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

현재 계정의 라인 아이템에 연결된 계정에 대한 특정 레퍼런스를 조회합니다.

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	해당 요청에서 작업 대상이 되는 프로모션 계정에 대한 참조입니다. Type: string Example: 19pl2
with_deleted optional	삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

POST accounts/:account_id/promoted_accounts

지정한 라인 아이템에 계정(user_id)을 연결합니다.

지정한 라인 아이템이 Promoted Accounts와의 연결로 구성되어 있지 않으면 HTTP 400 INCOMPATIBLE_LINE_ITEM 오류가 반환됩니다. 지정한 사용자가 프로모션 대상이 아니면 HTTP 400이 반환되며 어떤 사용자도 프로모션되지 않습니다. 제공한 사용자가 이미 프로모션된 상태라면 요청은 무시됩니다.

Promoted Accounts에 대한 자세한 내용은 campaign management 페이지를 참고하세요.

참고: promoted accounts 엔터티는 업데이트(PUT)할 수 없습니다.

Resource URL

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

Parameters

Name	Description
account_id required	활용 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_id required	요청에서 작업하는 라인 아이템에 대한 참조입니다. Type: string Example: 9bpb2
user_id required	요청에서 작업하는 사용자에 대한 참조입니다. 화면 이름에 대한 사용자 ID를 조회하려면 GET users/lookup을 사용하세요. Type: long Example: 756201191646691328

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

지정된 라인 아이템에서 계정 연결을 해제합니다.

리소스 URL

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

매개변수

Name	Description
account_id required	활용 중인 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
promoted_account_id required	라인 아이템과 연결된 Promoted Account 인스턴스의 식별자입니다. Type: string Example: 19pl2

요청 예시

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

응답 예시

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

​

프로모션 게시물

Postman에서 실행

​

GET accounts/:account_id/promoted_tweets

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

GET accounts/:account_id/tweets 엔드포인트를 사용해 Tweet 객체를 가져오세요. 각 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

매개변수

이름	설명
account_id 필수	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
promoted_tweet_id 필수	요청에서 대상이 되는 프로모션된 Tweet의 참조입니다. 유형: string 예시: 1efwlo
with_deleted 선택	삭제된 결과를 포함할지 여부입니다. 유형: boolean 기본값: false 가능한 값: 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

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

PROMOTED_ACCOUNT 제품 유형을 사용할 때 line_item에 게시물을 연결하면 표준 PROMOTED_ACCOUNT 게재 위치에 더해 모바일 타임라인 게재가 추가됩니다.

참고: 프로모션된 게시물 엔터티는 업데이트(PUT)할 수 없습니다.

Resource URL

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

Parameters

Name	Description
account_id required	연결된 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_id required	이 요청에서 작업 중인 라인 아이템에 대한 참조입니다. Type: string Example: 8v7jo
tweet_ids required	특정 게시물에 해당하는 식별자의 쉼표로 구분된 목록입니다. 최대 50개의 ID를 제공할 수 있습니다. Type: long Example: 822333526255120384

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

지정된 라인 아이템에서 트윗 연결을 해제합니다.

참고: 삭제된 promoted_tweets 엔터티는 ads.x.com UI에서 “Paused”로 표시됩니다. 마찬가지로 UI에서 “일시 정지”를 수행하면 해당 트윗이 해당 라인 아이템과의 연결이 해제됩니다.

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
promoted_tweet_id required	라인 아이템과 연결된 Promoted Tweet 인스턴스를 가리키는 식별자입니다. 해당 트윗의 tweet_id가 아니라 GET accounts/:account_id/promoted_tweets의 응답 항목에 포함된 id 필드 값입니다. 리소스 경로에 포함됩니다. Type: string Example: 1gp8a5

Example Request

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

Example Response

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

​

프로모션 대상 사용자

Postman에서 실행

​

GET accounts/:account_id/promotable_users

현재 계정과 연결된 프로모션 가능 사용자 일부 또는 전체의 세부 정보를 조회합니다.

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

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

대상 Tweet을 리트윗할 필요는 없습니다. 이 방식으로 Tweet을 프로모션하면 반환되는 tweet_id는 제공된 Tweet ID와 다릅니다. 내부적으로 해당 Tweet은 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	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 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

현재 계정과 연동된 특정 프로모션 대상 사용자(promotable user)를 조회합니다.

프로모션 대상 사용자 유형은 FULL 또는 RETWEETS_ONLY입니다. 이는 해당 계정이 프로모션할 수 있는 콘텐츠 유형을 결정합니다.

광고주는 다른 사용자의 콘텐츠를 프로모션하려면 권한을 획득해야 합니다. 권한이 올바르게 설정되어 있다면, 프로모션하려는 Tweet의 Tweet ID를 직접 참조하는 프로모션 제품 엔드포인트로 요청을 보낼 수 있습니다.

대상 Tweet을 리트윗할 필요는 없습니다. 이 방식으로 Tweet을 프로모션하면 반환되는 tweet_id는 제공한 Tweet ID와 다릅니다. 내부적으로 해당 Tweet은 nullcast된 Tweet으로 리트윗된 뒤 프로모션됩니다. 반환되는 tweet_id는 이 새로운 Tweet에 해당합니다.

Resource URL

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

Parameters

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

Example Request

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

Example Response

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

​

퍼블리셔

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

상태: 클로즈드 베타

이 광고 계정과 연관된 캠페인 추천을 조회합니다. 현재 자금 조달 수단당 추천은 1개로 제한됩니다.

리소스 URL

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

매개변수

이름	설명
account_id required	대상 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 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": "테스트용 권장 사항",
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

​

GET accounts/:account_id/recommendations/:recommendation_id

Status: 클로즈드 베타

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

캠페인 추천에는 객체 트리로 표현된 캠페인 구조에 대해 제안된 변경 사항 전체가 포함됩니다. 응답 트리는 Batch API 엔드포인트와 함께 사용하도록 설계되었지만, 필요에 따라 단일 업데이트 엔드포인트에 매핑할 수도 있습니다(POST는 생성, PUT은 업데이트, DELETE는 삭제).

Resource URL

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

Parameters

Name	Description
account_id 필수	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 요구되는 매개변수입니다. 지정된 계정은 인증된 사용자와 연계되어 있어야 합니다. Type: string Example: 18ce54d4x5t
recommendation_id 필수	이 요청에서 대상으로 하는 추천 ID에 대한 참조입니다. Type: string Example: 62ce8zza1q0w

Example Request

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

Example Response

{
    "request": {
      "params": {
        "recommendation_id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t"
      }
    },
    "data_type": "recommendations",
      "data": {
      "changes": [
        {
          "entity_type": "campaigns",
          "params": {
            "start_time": "2016-11-08T22:00:00Z",
            "daily_budget_amount_local_micro": 2200000,
            "end_time": "2016-11-16T07:59:00Z",
            "total_budget_amount_local_micro": 12000000,
            "id": "64m0d"
          },
          "operation_type": "Update",
          "dependent_entities": [
            {
              "entity_type": "line_items",
              "params": {
                "name": "추천 캠페인",
                "placements": [
                  "TWITTER_TIMELINE"
                ],
                "bid_amount_local_micro": 1430000,
                "id": "6f5kq",
                "include_sentiment": "ALL"
              },
              "operation_type": "Update",
              "dependent_entities": [
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6p"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "선거 결과",
                    "targeting_value": "선거 결과",
                    "targeting_type": "PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftp"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "남성",
                    "targeting_value": 1,
                    "targeting_type": "GENDER"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "샌프란시스코-오클랜드-산호세 CA, 미국",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101fto"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "91125952589766656"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "파트너 오디언스 타겟팅",
                    "targeting_value": "v2cx",
                    "targeting_type": "NEGATIVE_BEHAVIOR"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "AGE_21_TO_34",
                    "targeting_value": "AGE_21_TO_34",
                    "targeting_type": "AGE"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6o"
                  },
                  "operation_type": "Delete",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991101965843460096"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "line_item_id": "6f5kq",
                    "display_properties": [],
                    "paused": false,
                    "approval_status": "ACCEPTED",
                    "tweet_id": "991127212156096516"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "토론",
                    "targeting_value": "토론",
                    "targeting_type": "NEGATIVE_PHRASE_KEYWORD"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "line_item_id": "6f5kq",
                    "name": "60004, IL, 미국",
                    "targeting_value": "",
                    "targeting_type": "LOCATION"
                  },
                  "operation_type": "Create",
                  "dependent_entities": []
                },
                {
                  "entity_type": "targeting_criteria",
                  "params": {
                    "id": "a8po6n"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                },
                {
                  "entity_type": "promoted_tweets",
                  "params": {
                    "id": "101ftn"
                  },
                  "operation_type": null,
                  "dependent_entities": []
                }
              ]
            }
          ]
        }
      ],
      "funding_instrument_id": "gpvzb",
      "id": "62ce8zza1q0w",
      "account_id": "18ce54d4x5t",
      "status": "PENDING",
      "message": "테스트용 추천",
      "created_at": "2016-11-14T23:07:54Z",
      "updated_at": "2016-11-14T23:07:54Z"
      }
    }

​

예약된 프로모션용 게시물

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	식별자를 쉼표로 구분하여 제공해 특정 라인 아이템과 연결된 예약된 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

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

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

Resource URL

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

Parameters

Name	Description
account_id required	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
line_item_id required	요청에서 작업 중인 라인 아이템에 대한 참조입니다. Type: string Example: 8xdpe
scheduled_tweet_id required	요청에서 작업 중인 예약된 게시물에 대한 참조입니다. Type: long Example: 870358555227860992

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id

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

참고: scheduled_promoted_tweets는 예약된 트윗의 scheduled_at 시간 이전에만 삭제할 수 있습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
scheduled_promoted_tweet_id required	이 요청에서 대상으로 하는 예약 프로모션 트윗을 가리키는 참조입니다. GET accounts/:account_id/scheduled_promoted_tweets 응답 객체의 id 속성입니다. Type: string Example: 1xtfl

예시 요청

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

예시 응답

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

​

타게팅 기준

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

Example Request

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

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "8u94t"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8u94t",
          "name": "맞춤 오디언스 타겟팅",
          "id": "dpl3a6",
          "operator_type": "EQ",
          "created_at": "2017-05-26T03:29:35Z",
          "targeting_value": "249yj",
          "updated_at": "2017-05-26T03:29:35Z",
          "deleted": false,
          "targeting_type": "CUSTOM_AUDIENCE"
        }
      ]
    }

​

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

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

리소스 URL

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

매개변수

Name	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

예시 요청

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

예시 응답

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

​

POST accounts/:account_id/targeting_criteria

특정 타기팅 유형에 해당하는 targeting_value를 찾으려면 Targeting Options 페이지를 확인하세요. 최신 타기팅 값으로 작업할 수 있도록 모든 데이터를 매주 새로 고치길 권장합니다. 값과 사용 가능한 타기팅 기준은 수시로 변경됩니다. 대부분은 자주 바뀌지 않지만 일부는 변경됩니다. 이러한 값이 변하지 않음을 보장할 수 없습니다.

targeting_value에 지정된 키워드와 함께 BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD 타기팅 유형을 사용하세요. 키워드를 제외하려면 operator_type 요청 매개변수를 NE로 설정하세요. 각 유형에 대한 자세한 설명은 targeting keyword types을 참조하세요.

참고: 라인 아이템당 하나의 연령 버킷만 타기팅할 수 있습니다.

참고: Custom Audience를 타기팅하려면 해당 오디언스가 타기팅 가능해야 합니다. 즉, targetable이 반드시 true여야 합니다.

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

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	이 라인 아이템에 적용될 타기팅 유형입니다. 키워드 기반이 아닌 가능한 값: 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_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE Twitter Audience Platform(TAP) 앱 제외: APP_LIST (operator_type=NE와 함께만 사용 가능)
targeting_value required	선택한 targeting_type에 따라 어떤 사용자, 관심사, 위치, 이벤트, 플랫폼, 플랫폼 버전, 디바이스, 키워드 또는 구, 성별, Custom Audience, 앱 스토어 카테고리, 또는 앱 목록 제외에 이 타기팅을 적용할지 지정합니다. 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)을 일괄 생성할 수 있습니다.

배치 요청

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

배치 응답

배치 API 응답은 순서가 보장된 항목 컬렉션을 반환합니다. 그 외에는 해당 단일 항목 엔드포인트와 구조가 동일합니다.

배치 오류

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

리소스 URL

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

매개변수

이름	설명
operation_type 필수	각 항목에 대해 수행되는 작업 유형입니다. 유형: enum 가능한 값: Create, Delete
params 필수	타기팅 기준 객체에 대한 모든 매개변수를 포함하는 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": "맞춤 타겟 그룹 타겟팅",
        "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": "게임: 음악",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qouq",
          "os_type": "IOS"
        },
        {
          "name": "음악",
          "targeting_type": "APP_STORE_CATEGORY",
          "targeting_value": "qov2",
          "os_type": "IOS"
        }
      ],
      "request": {
        "params": {
          "q": "music",
          "os_type": "IOS"
        }
      }
    }

​

GET targeting_criteria/conversations

프로모션 제품에서 사용할 수 있는 대화 기반 타기팅 기준을 확인합니다.

Resource URL

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

Parameters

Name	Description
conversation_type optional	특정 대화 유형으로 범위를 한정하는 선택적 쿼리입니다. Type: enum Possible values: 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에 사용할 수 있는 이벤트 기반 타기팅 기준을 조회합니다. 라인 아이템당 타기팅할 수 있는 이벤트는 하나뿐입니다.

참고: 이벤트는 여러 시간대에 걸쳐 존재하는 경우가 많아, 서로 다른 시간대 관점에서 이벤트 시간을 고려할 때 복잡해질 수 있습니다. 이를 단순화하기 위해 이 엔드포인트의 모든 이벤트 start_time 및 end_time 값은 이벤트의 로케일과 시간대와 무관하게 UTC±00:00으로 표기됩니다. 이벤트 start_time 및 end_time 값을 조회하고 사용할 때 이 설계를 염두에 두시기 바랍니다. 예를 들어, 미국 독립기념일은 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: enum 가능한 값: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, POLITICS, RECURRING, SPORTS
count optional	각 요청에서 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
country_codes optional	특정 국가의 ISO 2자리 국가 코드를 사용해 타기팅 기준 검색 범위를 제한하기 위한 선택적 쿼리입니다. 이 매개변수를 지정하지 않으면 모든 이벤트가 반환됩니다. Type: string
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
end_time optional	캠페인이 종료되는 시간을 ISO 8601 형식으로 표현한 값입니다. Type: string Example: 2017-10-05T00:00:00Z
start_time optional	라인 아이템이 게재를 시작하는 시간을 ISO 8601 형식으로 표현한 값입니다. 참고: 기본값은 현재 시간입니다. Type: string Example: 2017-07-05T00:00:00Z

Example Request

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

Example Response

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

​

GET targeting_criteria/interests

Promoted Products용 관심사 기반 타기팅 기준을 확인하세요. 관심사는 자주 변경되지 않지만, 이 목록은 최소 주 1회 최신 상태로 갱신할 것을 권장합니다.

Resource URL

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

Parameters

Name	Description
count optional	각 요청당 조회할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
q optional	타기팅 기준을 범위 지정하기 위한 선택적 쿼리입니다. 전체를 가져오려면 이 매개변수를 생략하세요. Type: string Example: books

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "도서 및 문학/자서전 및 회고록",
          "targeting_type": "INTEREST",
          "targeting_value": "1001"
        }
      ],
      "request": {
        "params": {
          "q": "도서",
          "count": 1
        }
      },
      "next_cursor": "6by4n4"
    }

​

GET targeting_criteria/languages

타게팅에 사용할 수 있는 언어를 조회합니다.

Resource URL

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

Parameters

Name	Description
count optional	요청당 조회할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 페이지 결과를 가져오기 위한 커서를 지정합니다. 자세한 내용은 페이지네이션을 참조하세요. Type: string Example: 8x7v00oow
q optional	타게팅 기준을 제한하기 위한 선택적 쿼리입니다. 전체를 가져오려면 이 매개변수를 생략하세요. Type: string Example: english

Example Request

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

Example Response

    {
      "data": [
        {
          "name": "영어",
          "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 열거형을 사용하세요.

지정 시장 지역(DMA)을 타기팅하려면 METROS 열거형을 사용하세요.

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처럼 모바일 운영체제 버전의 포인트 릴리스 단위까지 정밀 타기팅할 수 있습니다.

Resource URL

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

Parameters

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

Example Request

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

Example Response

    {
        "data": [
            {...},
            {
                "name": "아이스크림 샌드위치",
                "number": "4.0",
                "os_type": "Android",
                "targeting_type": "PLATFORM_VERSION",
                "targeting_value": "17"
            },
            {
                "name": "젤리 빈",
                "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 휴대폰 및 태블릿",
          "targeting_type": "PLATFORM",
          "targeting_value": "2"
        },
        {
          "name": "기타 기기의 모바일 웹",
          "targeting_type": "PLATFORM",
          "targeting_value": "3"
        },
        {
          "name": "데스크톱 및 노트북",
          "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": "프랑스",
          "country_code": "FR",
          "locale": "fr-FR"
        },
        {
          "name": "칠레",
          "country_code": "CL",
          "locale": "es-CL"
        },
        {
          "name": "독일",
          "country_code": "DE",
          "locale": "de-DE"
        },
        {
          "name": "네덜란드",
          "country_code": "NL",
          "locale": "nl-NL"
        },
        {
          "name": "미국",
          "country_code": "US",
          "locale": "en-US"
        },
        {
          "name": "베네수엘라",
          "country_code": "VE",
          "locale": "es-VE"
        },
        {
          "name": "브라질",
          "country_code": "BR",
          "locale": "pt-BR"
        },
        {
          "name": "멕시코",
          "country_code": "MX",
          "locale": "es-MX"
        },
        {
          "name": "콜롬비아",
          "country_code": "CO",
          "locale": "es-CO"
        },
        {
          "name": "영국",
          "country_code": "GB",
          "locale": "en-GB"
        },
        {
          "name": "아르헨티나",
          "country_code": "AR",
          "locale": "es-AR"
        },
        {
          "name": "일본",
          "country_code": "JP",
          "locale": "ja-JP"
        },
        {
          "name": "캐나다",
          "country_code": "CA",
          "locale": "en-CA"
        },
        {
          "name": "스페인",
          "country_code": "ES",
          "locale": "es-ES"
        },
        {
          "name": "이탈리아",
          "country_code": "IT",
          "locale": "it-IT"
        },
        {
          "name": "미국 - 히스패닉계",
          "country_code": "US",
          "locale": "es-US"
        },
        {
          "name": "아일랜드",
          "country_code": "IE",
          "locale": "en-IE"
        }
      ],
      "request": {
        "params": {}
      }
    }

​

GET targeting_criteria/tv_shows

Promoted Products에서 사용할 수 있는 TV 프로그램 기반 타기팅 기준을 확인합니다. TV 프로그램 타기팅은 일부 시장의 Promoted Tweets에서 제공됩니다. 사용 가능한 시장은 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개의 키워드 또는 사용자 타기팅 제안을 가져옵니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	사용하는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 대부분의 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
suggestion_type 필수	반환할 제안의 유형을 지정합니다. 유형: enum 가능한 값: KEYWORD, USER_ID
targeting_values 필수	제안 생성을 위해 사용하는 키워드 또는 사용자 ID의 쉼표로 구분된 집합입니다. 참고: 두 유형의 제안을 혼합할 수 없습니다. 예시: 756201191646691328
count 선택	각 요청에서 가져올 레코드 수를 지정합니다. 유형: int 기본값: 30 최소, 최대: 1, 50

요청 예시

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

응답 예시

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

현재 계정에 연결된 세금 설정 상세 정보를 조회합니다.

리소스 URL

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

매개변수

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

예시 요청

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

예시 응답

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

현재 계정의 세금 설정을 업데이트합니다.

리소스 URL

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

매개변수

이름	설명
account_id 필수	사용할 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 광고주 API 요청에 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. 유형: string 예시: 18ce54d4x5t
address_city 선택 사항	계정 소유자 주소의 도시입니다. 유형: string 예시: San Francisco
address_country 선택 사항	계정 소유자 주소의 두 글자 국가 코드입니다. 유형: string 예시: US
address_email 선택 사항	계정 소유자 주소와 연결된 이메일입니다. 유형: string 예시: [e-mail]
address_first_name 선택 사항	계정 소유자 주소의 이름입니다. 유형: string 예시: API
address_last_name 선택 사항	계정 소유자 주소의 성입니다. 유형: string 예시: McTestface
address_name 선택 사항	계정 소유자 주소의 회사명입니다. 유형: string 예시: ABC, Co.
address_postal_code 선택 사항	계정 소유자 주소의 우편번호입니다. 유형: string 예시: 94102
address_region 선택 사항	계정 소유자 주소의 지역입니다. 유형: string 예시: California
address_street1 선택 사항	계정 소유자 주소의 거리 주소입니다. 유형: string 예시: 21 March St
address_street2 선택 사항	계정 소유자 주소의 두 번째 거리 주소입니다. 유형: string 예시: Suite 99
bill_to 선택 사항	청구 대상 주체입니다. 유형: enum 가능한 값: ADVERTISER, AGENCY
business_relationship 선택 사항	계정이 광고주 소유인지 대행사 소유인지 여부입니다. 유형: enum 가능한 값: AGENCY, SELF
client_address_city 선택 사항	광고주 주소의 도시입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: Toronto
client_address_country 선택 사항	광고주 주소의 두 글자 국가 코드입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: CA
client_address_email 선택 사항	광고주 주소와 연결된 이메일입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: [e-mail]
client_address_first_name 선택 사항	광고주 주소의 이름입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: Brand
client_address_last_name 선택 사항	광고주 주소의 성입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: Advertiser
client_address_name 선택 사항	광고주 주소의 회사명입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: Brand, Inc.
client_address_postal_code 선택 사항	광고주 주소의 우편번호입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: M5H 2N2
client_address_region 선택 사항	광고주 주소의 지역입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: Ontario
client_address_street1 선택 사항	광고주 주소의 거리 주소입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: 280 Queen St W
client_address_street2 선택 사항	광고주 주소의 두 번째 거리 주소입니다. 광고 계정이 대행사 소유인 경우 이 값을 설정합니다. 유형: string 예시: The 6
invoice_jurisdiction 선택 사항	송장 관할권입니다. 유형: 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 등록 ID입니다. 유형: 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

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

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며 GET accounts를 제외한 모든 Advertiser API 요청에 일반적으로 필요한 매개변수입니다. 지정한 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
count optional	각 요청에서 조회를 시도할 레코드 수를 지정합니다. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	다음 결과 페이지를 가져오기 위한 커서를 지정합니다. 자세한 내용은 Pagination을 참조하세요. Type: string Example: 8x7v00oow
line_item_ids optional	쉼표로 구분된 식별자 목록을 지정하여 특정 라인 아이템과 연결된 추적 태그만 응답에 포함하도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 96uzp
sort_by optional	지원되는 속성 기준으로 오름차순 또는 내림차순 정렬합니다. 자세한 내용은 Sorting을 참조하세요. Type: string Example: created_at-asc
tracking_tag_ids optional	쉼표로 구분된 식별자 목록을 지정하여 원하는 추적 태그만 응답에 포함하도록 범위를 제한합니다. 최대 200개의 ID를 제공할 수 있습니다. Type: string Example: 3m82
with_deleted optional	삭제된 결과를 응답에 포함합니다. Type: boolean Default: false Possible values: true, false
with_total_count optional	total_count 응답 속성을 포함합니다. Note: 이 매개변수와 cursor는 상호 배타적입니다. Note: total_count를 포함하는 요청에는 더 낮은 요청 한도가 적용되며, 현재 15분당 200으로 설정되어 있습니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

GET accounts/:account_id/tracking_tags/:tracking_tag_id

현재 계정에 연결된 특정 추적 태그를 조회합니다.

Resource URL

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

Parameters

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필수 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
tracking_tag_id required	해당 요청에서 대상으로 하는 추적 태그의 참조입니다. Type: string Example: 555j
with_deleted optional	삭제된 결과를 포함할지 여부입니다. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

​

POST accounts/:account_id/tracking_tags

지정한 라인 아이템에 트래킹 태그를 연결합니다.

리소스 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

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

Resource URL

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

Parameters

Name	Description
account_id required	사용되는 계정의 식별자입니다. 리소스 경로에 포함되며, GET accounts를 제외한 모든 Advertiser API 요청에서 일반적으로 필요한 매개변수입니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
tracking_tag_url required	추적 파트너가 제공한 추적 태그 URL입니다. Type: string Example: https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309

Example Request

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

Example Response

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

​

DELETE accounts/:account_id/tracking_tags/:tracking_tag_id

지정한 라인 아이템에서 트래킹 태그의 연결을 해제합니다.

리소스 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

요청 예시

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

응답 예시

    {
      "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 Example: 18ce54d4x5t
user_id required	요청에서 작업 대상인 사용자를 참조합니다. 화면 이름의 사용자 ID를 조회하려면 GET users/lookup을 사용하세요. Type: long Example: 756201191646691328

Example Request

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

Example Response

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

​

PUT accounts/:account_id/user_settings/:user_id

사용자 설정을 업데이트합니다. 사용자 컨텍스트가 필요합니다. 계정 관리자는 접근할 수 없습니다.

리소스 URL

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

매개변수

Name	Description
account_id required	사용 중인 계정의 식별자입니다. 리소스 경로와 GET accounts에 표시됩니다. 지정된 계정은 인증된 사용자와 연결되어 있어야 합니다. Type: string Example: 18ce54d4x5t
user_id required	요청에서 조작 대상으로 하는 사용자를 참조합니다. 화면 이름에 대한 사용자 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

예시 요청

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

예시 응답

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