X Ads API의 이전 버전에 대한 최신 정보는 아래 표를 참고하세요.Documentation Index
Fetch the complete documentation index at: https://generaltranslation.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
| Version | Path | 도입일 | 지원 중단일 | 서비스 종료일 |
|---|---|---|---|---|
| 12.0 | /12/ | 2022년 10월 27일 | 미정 | 미정 |
| 11.0 | /11/ | 2022년 3월 31일 | 미정 | 미정 |
| 10.0 | /10/ | 2021년 8월 31일 | 2022년 3월 31일 | 2022년 10월 27일 |
| 9.0 | /9/ | 2021년 3월 2일 | 2021년 8월 31일 | 2022년 3월 31일 |
| 8.0 | /8/ | 2020년 9월 8일 | 2021년 3월 2일 | 2021년 8월 31일 |
| 7.0 | /7/ | 2020년 3월 3일 | 2020년 9월 1일 | 2021년 3월 2일 |
| 6.0 | /6/ | 2019년 8월 28일 | 2020년 3월 3일 | 2020년 9월 1일 |
| 5.0 | /5/ | 2019년 2월 28일 | 2019년 8월 28일 | 2020년 3월 3일 |
| 4.0 | /4/ | 2018년 8월 28일 | 2019년 2월 28일 | 2019년 8월 28일 |
| 3.0 | /3/ | 2018년 2월 1일 | 2018년 8월 28일 | 2019년 2월 28일 |
| 2.0 | /2/ | 2017년 7월 10일 | 2018년 2월 1일 | 2018년 8월 1일 |
| 1.0 | /1/ | 2016년 3월 31일 | 2017년 7월 7일 | 2018년 1월 10일 |
| 0.0 | /0/ | 2013년 2월 21일 | 해당 없음 | 2016년 10월 31일 |
개요
- API 요청/응답에서 파라미터를 제거하는 것
- 파라미터나 엔드포인트의 이름을 변경하는 것
- 값 표현 방식 변경 (preview_url → card_uri)
- 엔드포인트 동작 방식 변경 (예: 비동기(async) vs 동기(sync) 통계)
- 선택적 또는 필수 파라미터를 추가/변경하는 것 (예: 요청에서 name을 필수 필드로 만드는 경우)
버전 관리 전략
- 모든 하위 호환성을 깨는 변경 사항은 새 버전에 묶어서 제공됩니다.
- 새 버전이 발표될 때 기존 버전에 대한 사용 중단(deprecation) 유예 기간은 6개월입니다.
- 언제든지 API는 두 개의 버전에서 오는 요청을 동시에 허용하지만, 이 둘 중 오래된 버전은 지원되지 않습니다.
- 새로운 제품을 더 빠르게 도입할 수 있도록, 이러한 제품은 버전 관리 주기와는 별도로 지속적으로 출시됩니다.
-
모든 API 응답에는
x-current-api-version이 포함되며, 이 값은 현재 API 버전으로 설정됩니다. 또한 사용 중단된(deprecated) API endpoint를 호출하는 경우x-api-warn헤더가 추가로 포함됩니다.
v9
Note: 이번 릴리스 시점부터 Ads API 버전 7(v7)은 지원이 종료되어 더 이상 사용할 수 없습니다.
v8
v7
v6
v5
accounts/:account_id/account_media endpoint는 사용 중단(deprecated)되었습니다.
이전 버전과 마찬가지로, v5로 마이그레이션하기 위한 6개월 전환 기간이 제공됩니다. 2019-08-28 이후로는 Ads API 버전 4를 더 이상 사용할 수 없습니다. 모든 파트너가 서비스 중단을 방지하기 위해 가능한 한 빨리 최신 버전의 API로 마이그레이션할 것을 권장합니다. Ads API 버전 3은 수명이 종료(end of life)되어 더 이상 제공되지 않습니다.
신규
CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_TWEET.
MEDIA_CREATIVE 통계
Ads API의 애널리틱스 엔드포인트는 이제 Media Creative 엔티티에 대한 메트릭을 제공합니다. Media Creative는 X Audience Platform에서 인스트림 광고 또는 이미지를 프로모션하는 방식입니다. X Ads UI에서는 “In-stream videos” 및 “Display creatives” 탭에서 Media Creative 메트릭을 표시합니다. 동기식과 비동기식 애널리틱스 엔드포인트 모두 이제 MEDIA_CREATIVE 엔티티 enum을 지원합니다.
여러 카드 가져오기
카드 URI 값으로 단일 카드를 조회하도록 설계된 엔드포인트의 v3 릴리스를 개선하여, 이제 GET accounts/:account_id/cards/all 엔드포인트를 사용해 여러 카드를 가져올 수 있습니다. 이제 각 카드마다 요청을 보내는 대신, 한 번의 요청으로 최대 200개의 카드를 조회할 수 있습니다.
다음 두 가지를 유의하십시오.
- URL 경로는 이제
accounts/:account_id/cards/all입니다. (이전 경로는 더 이상 사용할 수 없습니다.) 이는 ID로 카드를 조회하도록 설계된 엔드포인트와의 일관성을 유지하기 위함입니다. - 필수 요청 파라미터 이름은 이제 card_uris(복수형)입니다.
- GET accounts/:account_id/line_item_apps
- GET accounts/:account_id/media_creatives
- GET accounts/:account_id/promoted_accounts
- GET accounts/:account_id/preroll_call_to_actions
변경 사항
draft_only | with_draft | |
Network Activation Duration 타게팅
Ads API에서는 Network Activation Duration 타게팅을 추가한 이후, 응답의 타게팅 type에 _IN_SEC 접미사가 포함되던 표시 문제를 해결했습니다. Network Activation Duration은 항상 개월 단위로 표현되므로, 초(second)에 대한 참조는 혼란을 줄 수 있었습니다. 이번 수정으로 표현 방식이 일관되게 되어 혼동이 줄어듭니다.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
전체 개수 및 커서
v5에서는 with_total_count와 cursor가 상호 배타적입니다. 요청에 둘 다 지정하면 EXCLUSIVE_PARAMETERS 오류 코드를 반환합니다. v5 이전에는 cursor가 지정된 경우 with_total_count는 무시되었습니다. 이번 변경으로 둘 사이의 관계가 명시적으로 정의됩니다.
제거됨
- v4에서 카드에 대한 preview_url 응답 매개변수가 항상 null이라고 이미 공지되었습니다. 이 마이그레이션의 마지막 단계는 모든 카드 응답에서 preview_url을 제거하는 것입니다.
- 다음 리소스의 경우 ads 계정 ID가 이미 URL 및 request.params에 포함되어 있으므로 account_id 응답 속성이 제거됩니다. (펀딩 인스트루먼트는 의도적으로 이 목록에서 제외됩니다. 가능한 경우 parent ID는 응답 객체에 포함되어야 하며, account ID는 펀딩 인스트루먼트의 상위 엔티티이기 때문입니다.)
- 계정 미디어
- App 이벤트 공급자
- App 이벤트 태그
- 캠페인
- 카드
- 라인 아이템
- 프로모션 대상 사용자
- 타기팅 기준
- GET accounts/:account_id/targeting_criteria 요청의 경우, parent_ids 필드는 항상 빈 배열이었기 때문에 더 이상 반환되지 않습니다.
- 참고: 이는 이미지 및 동영상 app 다운로드 카드에는 영향을 미치지 않습니다.
- Media Library에 추가된
AMPLIFY_VIDEO애셋은PREROLL크리에이티브 타입으로 자동으로 Account Media 애셋으로 추가됩니다. - 특정 규격의 이미지를 Media Library에 추가하면 자동으로 Account Media 애셋으로 추가됩니다. 크리에이티브 타입(예:
INTERSTITIAL)은 이미지 규격에 따라 달라집니다. (규격에 대한 자세한 내용은 Enumerations 페이지를 참조하세요.)
v4
신규
- TON 업로드:
- GET accounts/:account_id/tailored_audience_changes
- GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
- POST accounts/:account_id/tailored_audience_changes
- PUT accounts/:accounti_d/tailored_audiences/global_opt_out
- 실시간 오디언스:
- POST tailored_audience_memberships
list_type 파라미터가 제거됩니다.
Settings 엔드포인트
이제 계정 관리자가 사용자, 계정, 세금 설정을 설정하고 업데이트할 수 있습니다. User settings는 특정 광고 계정에 대한 사용자별 연락 설정 선호도를 의미합니다. PUT accounts/:account_id 엔드포인트를 사용하여 광고주는 이제 계정 이름과 산업 유형을 업데이트할 수 있습니다. 마지막으로, tax settings 엔드포인트를 통해 부가가치세(VAT)가 부과되는 국가의 광고주는 회사명, 주소, VAT ID, 계정이 광고주가 직접 소유한 것인지 또는 대행사가 광고주를 대신해 계정을 소유하는지와 같은 정보를 업데이트할 수 있습니다.
변경 사항
lookalike_expansion 매개변수의 enum 값을 변경했습니다.
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code 사용
Ads API 전반의 일관성을 높이기 위한 작업의 일환으로, 다음 엔드포인트들의 매개변수 이름을 app_country_code에서 country_code로 변경했습니다.
- POST accounts/:account_id/cards/image_app_download
- PUT accounts/:account_id/cards/image_app_download/:card_id
- POST accounts/:account_id/cards/video_app_download
- PUT accounts/:account_id/cards/video_app_download/:card_id
preview_url은 항상 null
v3 공지에서 약속한 대로, 이제 모든 기존 카드에는 card_uri가 있습니다. 그 결과 preview_url 값은 항상 null입니다.
참고로, card_uri 값을 사용해 카드를 Tweet에 연결할 수 있습니다. 다음 예시 요청을 참고하세요.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
제거됨
-
v3 videos 엔드포인트:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
v4 동영상용 Media Library 엔드포인트:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id
GET accounts/:account_id/tweet/preview/:tweet_id 엔드포인트에서 사용 가능하던 as_user_id 파라미터는 더 이상 허용되지 않습니다. 미리보기는 항상 Tweet 작성자 기준으로 렌더링됩니다.
v3
- 입력 오디언스를 기준으로 상위 관련 해시태그, @핸들, 이벤트를 조회합니다.
- 입력 오디언스를 기준으로 핵심 인구통계 정보(예: 나이, 성별, 가구 소득)를 조회합니다.
- 키워드를 기준으로 Tweet 볼륨 시계열 데이터를 조회합니다.
기타 변경 사항
- 이제 GET insights/keywords/search 엔드포인트의 응답에 입력 키워드와 관련된 30개의 용어를 포함하는
related_keywords속성이 추가되었습니다.
- 타기팅 기준 배치의 최대 크기가 이제 500으로 증가했습니다.
card_uri와preview_url응답 속성은 이제 상호 배타적입니다. 카드에card_uri가 있는 경우preview_url은null이 됩니다. 카드에card_uri가 없는 경우에는preview_url만 반환됩니다.- 2018-01-29 이후에 생성된 모든 카드는
card_uri를 갖습니다. - 버전 4까지는 기존의 모든 카드가
card_uri를 갖게 됩니다.
- 2018-01-29 이후에 생성된 모든 카드는
- 5:2 이미지가 있는 카드를 새로 생성하는 것은 더 이상 불가능합니다. 기존의 5:2 이미지 기반 카드는 계속 동작하지만, 파트너 여러분께는 (지원되는 경우) 성과가 더 좋은 1.91:1 또는 1:1 종횡비로 전환하실 것을 권장합니다.
- PUT accounts/:account_id/targeting_criteria 엔드포인트는 더 이상 사용할 수 없습니다. 이 엔드포인트의 replace 동작이 광고주에게 혼란을 주었고, 한 번에 하나의 리소스만 업데이트하는 다른 PUT 엔드포인트와 일관되지 않았기 때문에 이 변경을 적용하기로 결정했습니다. 대신 파트너 여러분은 POST batch/accounts/:account_id/targeting_criteria 엔드포인트를 사용해야 하며, 이 엔드포인트는 하나의 요청에서 타기팅을 추가 및 제거를 모두 할 수 있는 등 더 큰 유연성을 제공합니다.
paused응답 속성은 더 이상 자금 수단(funding instruments)에 대해 반환되지 않습니다. 대신 자금 수단이 일시 중지되었는지 여부를 확인하려면entity_status응답 속성을 참조하십시오. 또한paused와cancelled가 동일한 값을 가리키므로,cancelled역시 응답에서 더 이상 반환되지 않습니다.- GET accounts/:account_id/tweet/preview 엔드포인트에서
card_id파라미터를 제거했습니다. - 삭제된 예약 Tweet은 조회할 수 없기 때문에
with_deleted파라미터는 더 이상 지원되지 않습니다. - 다음 엔드포인트에서
draft_only파라미터가 제거되었습니다. 이 엔티티는 초안 상태가 될 수 없기 때문입니다.
v2
-
total_count는 이제 선택적 응답 속성입니다.with_total_count가true로 설정된 경우에만 제공됩니다. -
line_items및campaigns요청 및 응답 객체의paused및draft_only필드는 단일entity_status파라미터로 대체되었습니다. -
POST accounts/:account_id/tweet 및 GET accounts/:account_id/tweet/preview 엔드포인트에서
status파라미터 이름이text로 변경되었습니다. -
GET targeting_criteria/locations 엔드포인트의
location_typeenum 값이 복수형으로 변경되었습니다.COUNTRY는 이제COUNTRIES,REGION은 이제REGIONS이며, 기타 값도 동일한 규칙이 적용됩니다. 단, v2에서는CITY가METROS로 변경되어, 위치 타입이 Designated Marker Areas(DMA) 또는 “metros”를 가리킨다는 점을 정확히 반영합니다. -
PUT accounts/:account_id/promoted_tweets 엔드포인트에서
display_properties속성이 제거되었습니다. 이 값은 응답의 일부로도 더 이상 반환되지 않습니다. - 위 변경으로 인해, 더 이상 promoted_tweets 엔티티를 업데이트(PUT)할 수 없습니다.
-
GET accounts/:account_id/promoted_tweets 엔드포인트의
line_item_id파라미터가 제거되었습니다. - v2 엔드포인트에서는 더 이상 5:2 Website Card를 생성할 수 없습니다.
-
data_type응답 속성은 더 이상 반환되지 않습니다.
- Cards v2
- 초안 캠페인/라인 아이템 생성 및 활성화
- 예약 Tweet
- 비동기 작업 요약
- Tweet과 카드를 연결할 때 Tweet 텍스트에
preview_url을 추가하는 방식 대신card_uri요청 파라미터를 사용해야 합니다. - (카드 생성 단계에서) 응답에
card_uri파라미터가 반환되지 않는 경우preview_url을 사용하십시오. - 모든 신규 카드 포맷은
card_uri파라미터를 활용하는 네이티브 형식으로 API에서 제공됩니다.
- Video Website Cards:
- POST accounts/:account_id/line_items 및 POST accounts/:account_id/campaigns 엔드포인트의
entity_status파라미터 값을DRAFT로 설정하면 새로운 초안 캠페인이나 라인 아이템을 생성할 수 있습니다. - 새로 생성하는 초안에 필요한 필수 파라미터:
| Draft Campaign | Draft Line Item |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- 초안 라인 아이템 또는 캠페인은
entity_status가DRAFT인 상태에서만PAUSED또는ACTIVE로 전환할 수 있습니다. - 여러 라인 아이템이 있는 전체 캠페인을 활성화하려면, 캠페인에 속한 각 라인 아이템과 캠페인 자체 모두의
entity_status를ACTIVE로 설정해야 합니다. - 캠페인 또는 라인 아이템의
entity_status를 변경하려면, 해당하는 PUT 엔드포인트를 사용하십시오.
- Scheduled Tweets는 다음과 같은 새로운 엔드포인트로 구성됩니다.
- Scheduled Tweets:
- Campaign Management:
- 새로 예약된 Tweets는 미래의 임의의 날짜로 예약할 수 있습니다.
- 현재로서는 예약된 Tweet을 미리 볼 수 있는 기능이 없습니다.
-
SCHEDULED상태의 Scheduled Tweets만 편집/삭제할 수 있습니다. -
Scheduled Tweets는
scheduled_at날짜/시간까지 엔터프라이즈 Firehose 또는 다른 어떤 데이터 API로도 전파되지 않습니다.
v1
- 버전 관리 지원
CUSTOM목표는 더 이상 지원되지 않습니다- 배치 엔드포인트는 이제 정식 출시되었습니다
- 도달수 추정치 변경 사항:
- 더 정확한 도달 범위 추정을 위해 이 엔드포인트는 이제 예산을 고려합니다. 이제 다음 매개변수가 필수입니다:
- [신규]
campaign_daily_budget_amount_local_micro currencybidobjective
- [신규]
- 응답 객체의 구조가 변경되어 이제 응답 값에 대한 범위를 반환합니다.
infinite_count는 역할에 대한 혼동을 피하기 위해infinite_bid_count로 이름이 변경되었습니다.count및infinite_bid_count외에 이제 다음과 같은 새로운 데이터 포인트가 반환됩니다:impressionsengagementsestimated_daily_spend_local_micro
- Tailored Audiences 데이터 type 변경
- 모든 응답에서 Tailored Audiences의
data_type값이tailored_audiences에서tailored_audience로 변경되었습니다. - Shared Tailored Audiences 기능이 이제 API 전용 베타로 제공됩니다. Shared Tailored Audiences를 사용하면 하나의 오디언스를 여러 광고 계정에서 함께 사용할 수 있습니다. 여러 광고 계정에서 공유하려는 맞춤형 오디언스의 권한을 관리하려면 POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions 및 관련 엔드포인트를 사용하세요.
- 광고주 계정의 성과 analytics를 수집하는 방식이 크게 개선되었습니다:
- 모범 사례에 맞추기 위해, 이제 동기식 통계 엔드포인트에 대해서는 최대 7일분의 데이터만 조회할 수 있습니다.
- 메트릭 조회를 간소화하기 위해
metrics파라미터를 새로운metric_groups파라미터로 대체했습니다. 이제 개발자는 특정 요청에 대해 어떤 메트릭 그룹을 반환받을지 반드시 명시해서 요청해야 합니다.- 특정 엔티티에 적합하지 않은 메트릭을 요청하면, 해당 메트릭은 응답에서 제외되고
null값으로 표시됩니다. 이러한 메트릭은 분석 비용 한도에 산정되지 않습니다.
- 특정 엔티티에 적합하지 않은 메트릭을 요청하면, 해당 메트릭은 응답에서 제외되고
- 응답이 대폭 단순화되어 이제 UI에서 메트릭이 노출되는 방식과 보다 가깝게 일치합니다.
- 이전에는 각 게재 위치(검색에서의 Promoted Tweets, 타임라인에서의 Promoted Tweets, 프로필 및 Tweet 상세에서의 Promoted Tweets, X Audience Platform)에 대해 별도의 지표를 제공했습니다. 이제는 각 위치에 대해 표준화된 지표 세트를 반환합니다. 즉, 더 이상
promoted_tweet_timeline_impressions,promoted_tweet_search_impressions,promoted_tweets_profile_impressions,promoted_tweets_tpn_impressions를 사용하지 않고, 다음 카테고리 중 하나로 요청할 때 단일 지표인impressions로 제공되며, 이는 모든 지표에 적용됩니다: ALL_ON_TWITTERPUBLISHER_NETWORK- 요청을 보내면 UI의 값과 일치시키기 쉽도록 단일
impressions지표만 받게 됩니다. ALL_ON_TWITTER와PUBLISHER_NETWORK데이터를 모두 얻으려면, 이 둘은 결합할 수 없으므로 두 개의 쿼리를 수행해야 합니다.
- 이전에는 각 게재 위치(검색에서의 Promoted Tweets, 타임라인에서의 Promoted Tweets, 프로필 및 Tweet 상세에서의 Promoted Tweets, X Audience Platform)에 대해 별도의 지표를 제공했습니다. 이제는 각 위치에 대해 표준화된 지표 세트를 반환합니다. 즉, 더 이상
- 비동기 통계 엔드포인트를 이제 개발자 여러분의 피드백을 반영해 사용할 수 있습니다!
- 통계를 비동기적으로 요청할 수 있는 새 엔드포인트 세트로, 즉시 필요하지 않은 데이터나 과거 데이터 조회에 사용할 수 있습니다.
- 새로운 단일 엔드포인트를 통해 통계 job을 큐에 등록합니다. 사용 가능한 리소스 범위 내에서 요청하신 데이터를 수집합니다.
- 데이터 사용 가능 여부를 확인하기 위해 job status 엔드포인트를 조회할 수 있습니다.
- 데이터가 준비되면, 동기식 엔드포인트의 응답을 그대로 반영한 JSON 응답을 다운로드할 수 있도록 pick-up ID를 제공합니다.
- 하나의 job에서 최대 90일치 데이터와 최대 20개 엔티티에 대한 데이터를 조회할 수 있습니다.
- v0 지표를 v1 지표에 매핑한 내용을 포함한 analytics v1 마이그레이션 가이드를 확인하세요
- Sandbox 개선 사항 * 이제 Sandbox 환경에서 여러 개의 테스트용 광고 계정을 생성할 수 있습니다. * 이제 Sandbox 환경에서 테스트용 광고 계정에 대해 여러 개의 결제 수단을 생성할 수 있습니다. 이를 통해 모든 결제 수단 type을 테스트할 수 있습니다. 이전에는 테스트에 사용할 수 있는 결제 수단이
CREDIT_CARD하나뿐이었습니다. * 베타 기능을 테스트해 보고 싶으신가요? 이제 Sandbox 환경에서 계정별로 기능을 켜거나 끌 수 있으므로, 테스트 요구 사항에 맞게 설정할 수 있습니다.