메인 콘텐츠로 건너뛰기

​
소개

애널리틱스 지표는 파트너와 광고주가 X에서 프로모션하는 콘텐츠의 성과를 파악하는 데 도움을 줍니다. 여기에는 노출 수, 클릭 수, 동영상 조회 수, 지출액 등의 정보가 포함됩니다. 또한 파트너와 광고주는 도달한 오디언스를 다양한 세그먼트로 나눠 상세 지표를 확인할 수 있습니다. Ads API는 캠페인 성과의 상세 지표를 동기(synchronous)와 비동기(asynchronous) 두 가지 방식으로 제공합니다. 동기 애널리틱스 호출의 경우, 요청한 지표가 응답으로 바로 반환됩니다. 비동기 애널리틱스 엔드포인트의 경우, 관련 “작업(job)” 처리가 완료된 후 다운로드 가능한 결과 파일에서 요청한 지표를 확인할 수 있습니다. 동기 엔드포인트는 짧은 기간 범위를 지원하며 실시간 캠페인 최적화에 적합합니다. 비동기 엔드포인트는 훨씬 더 긴 기간 범위를 지원하므로 더 많은 데이터를 가져오는 데 적합해, 리포트 생성이나 과거 데이터 보강에 이상적입니다.

​
자세한 내용

​
동기식 vs. 비동기식

동기식과 비동기식 애널리틱스 엔드포인트의 차이점은 아래 표에 요약되어 있습니다. 이 정보는 개발자가 어떤 엔드포인트 세트를 사용할지 선택하는 데 도움이 되도록 제공됩니다.
기능동기식비동기식
레이트 제한사용자 수준: 15분당 250건 요청계정 수준: 동시에 최대 100건 작업*
기간7일90일(세그먼트 미적용)
45일(세그먼트 적용)
세분화아니오예
응답 내용메트릭 데이터작업 처리 상태**
권장 사용 사례실시간 최적화
사용자 인터페이스 요청		정기 동기화
과거 데이터 백필
  • 어느 시점이든 처리 중 상태에 둘 수 있는 작업의 최대 개수를 의미합니다.
** 작업 처리가 성공적으로 완료되면 URL이 반환됩니다. 해당 URL에서 압축(gzip)된 결과 파일을 다운로드할 수 있습니다.이 외에는 두 엔드포인트 모두 동일한 기능을 제공합니다.

​
사용 사례

세 가지 주요 분석 사용 사례가 있습니다.
  1. 실시간 최적화: 성과 지표를 활용해 진행 중인 캠페인 업데이트
  2. 동기화: 정기 일정에 따른 백그라운드 동기화
  3. 신규 계정 온보딩: 과거 데이터 백필
동기식 분석 엔드포인트는 최근 5~15분 내 지표 변화에 따라 캠페인을 업데이트하는 실시간 최적화에 사용할 수 있습니다. 동기화에는 어느 엔드포인트든 사용할 수 있습니다. 원하는 시간 범위와 세분화 필요 여부에 따라 사용할 엔드포인트가 결정됩니다. 신규 계정 온보딩은 비동기식 분석 엔드포인트만 사용해야 합니다. (동기식 분석 엔드포인트는 대량 데이터 조회에 절대 사용하면 안 됩니다.) 비동기식 분석 엔드포인트는 지표를 백엔드 프로세스와 동기화하는 경우 대시보드 및 기타 UI 요소를 구동할 수 있습니다. 구현 시 사용자 인터페이스 요청을 처리하기 위해 비동기식 분석 엔드포인트를 호출하는 것은 피해야 합니다.

​
요청 옵션

Analytics 요청은 광고 계정 단위로 범위가 지정되므로 리소스 경로에 계정 ID가 필요합니다. 아래 나열된 요청 옵션은 쿼리 매개변수로 지정됩니다. 다음 값 유형이 필요합니다.
  • 엔터티: 엔터티 유형과 분석을 요청할 최대 20개의 엔터티 ID
  • 시간 범위: ISO 8601 형식의 시작 및 종료 시간
    • 참고: 반드시 정시(whole hour) 단위여야 합니다
  • 메트릭 그룹: 관련 메트릭의 하나 이상의 집합(각 메트릭 그룹에 포함된 메트릭 목록은 Metrics and Segmentation 참조)
  • 세분성: 메트릭이 반환될 집계 수준 지정
  • 노출 위치: X 온사이트/오프사이트에서 집행된 광고의 메트릭을 조회할지 결정
    • 참고: 요청당 하나의 노출 위치 값만 지정할 수 있습니다
start_time 및 end_time 요청 매개변수로 시간 범위를 지정합니다. 이 값은 아래와 같이 지정한 세분성과 정렬되어야 합니다.
  1. TOTAL: 임의의 시간 범위를 지정(엔드포인트 한도 내)
  2. DAY: 시작 시간과 종료 시간 모두 계정의 시간대 기준 자정에 정렬되어야 함
  3. HOUR: 임의의 시간 범위를 지정(엔드포인트 한도 내)
종료 시간은 배타적입니다. 예를 들어 start_time=2019-01-01T00:00:00Z, end_time=2019-01-02T00:00:00Z로 요청하면 이 시간 범위가 24시간만 포함하므로 하루치의 분석 메트릭만 반환됩니다(둘이 아님). 세그멘테이션 비동기 분석 엔드포인트에서만 제공되는 세그멘테이션은 파트너와 광고주가 특정 타기팅 값별로 분리된 메트릭을 조회할 수 있도록 합니다. 세그멘테이션된 메트릭을 요청하려면 segmentation_type 요청 매개변수를 사용하세요. 세그멘테이션 옵션에 대한 자세한 내용은 Metrics and Segmentation을 참조하세요.

​
자주 묻는 질문

왜 Ads API 수치가 X Ads UI에 표시되는 값과 일치하지 않나요?
  • 두 가지 게재 위치 모두에 대한 데이터를 요청했는지 확인하세요: ALL_ON_TWITTER 및 PUBLISHER_NETWORK, SPOTLIGHT, TREND.
  • Ads API의 종료 시간은 배타적이지만, Ads UI에서는 포함됩니다.
왜 데이터를 요청하는 시점에 따라 수치가 달라지나요?
  • 보고 지표가 사용 가능해지는 즉시 조회할 수 있습니다. 거의 실시간으로 제공됩니다. 다만 이러한 초기 결과는 추정치이므로 변경될 수 있습니다. 지표는 지출 데이터를 제외하고 24시간 후에 확정됩니다.
  • 지출 지표는 일반적으로 이벤트 발생 후 3일 이내에 확정됩니다. 다만 청구 데이터는 스팸 필터링 등의 이유로 이벤트 발생일로부터 최대 14일간 처리됩니다.
특정 기간에 어떤 엔터티 id를 요청해야 하는지 어떻게 판단하나요? 애널리틱스 응답의 모든 값이 null인 이유는 무엇인가요?
  • 요청한 기간 동안 캠페인이 집행되지 않았을 가능성이 높습니다.
  • 어떤 엔터티에 대해 어떤 기간의 애널리틱스를 가져올지 판단하기 위해 Active Entities 엔드포인트를 사용하세요.
왜 API는 null 값을 보여주는데 UI는 0을 표시하나요?
  • UI는 이러한 값을 0으로 표시하도록 선택했을 뿐이며, 값의 의미는 동일합니다.
X 타임라인과 같은 세분화된 게재 위치와 연관된 지표는 어떻게 요청하나요?
  • 애널리틱스에서 다음 게재 위치 값을 지원합니다: ALL_ON_TWITTER 및 PUBLISHER_NETWORK, SPOTLIGHT, TREND(즉, X Audience Platform).
삭제되었거나 일시 중지된 엔터티에 대한 지표를 조회할 수 있나요?
  • 가능합니다. 엔터티의 상태는 애널리틱스 지표의 가용성에 영향을 주지 않습니다.
세그먼트된 값이 비세그먼트 값과 일치하지 않는 이유는 무엇인가요?
  • 이 정보의 산출 방식 때문에 세그먼트된 데이터가 비세그먼트 데이터와 100% 일치하도록 집계되지는 않습니다.
여러 차원으로 세그먼트된 데이터를 요청할 수 있나요?
  • 다중 세그멘테이션은 지원하지 않습니다.

​
모범 사례

Ads API에서 analytics 데이터를 수집할 때 유의할 모범 사례입니다.

​
속도 제한 및 재시도

  • 속도 제한이 적용된 쿼리(HTTP 429 상태 코드 반환)에서는 x-rate-limit-reset 헤더를 확인하고, 표시된 시점에 또는 그 이후에만 재시도해야 합니다.
  • HTTP 503 Service Unavailable 상태 코드가 반환된 쿼리에서는 retry-after 헤더를 확인하고, 표시된 시간 이후에만 재시도해야 합니다.
  • 지정된 재시도 시간을 준수하지 않는 애플리케이션은 예고 없이 Ads API에 대한 액세스가 취소되거나 제한될 수 있습니다.

​
분석 메트릭 한눈에 보기

  • billed_charge_local_micro를 제외한 모든 분석 메트릭은 24시간 후 확정되어 변경되지 않습니다.
  • billed_charge_local_micro 메트릭은 데이터가 반환된 후 최대 3일 동안 추정치로 제공됩니다.
  • 24시간 이후에는 초과 지출에 대한 크레딧(지정된 end_time 이후에 게재된 광고)과 정크로 판정된 과금 이벤트에 대한 크레딧으로 인해 이 메트릭이 감소할 수 있습니다. 이 메트릭은 24시간 이후에는 변경 폭이 매우 작습니다.
  • 자세한 내용은 Analytics를 참조하세요.

​
실시간 비분할 데이터 가져오기

  • 항상 start_time과 end_time을 함께 제공하세요.
  • 7일을 넘은 엔티티의 데이터는 가져오지 마세요.
  • 가능하면 HOUR 단위로 데이터를 요청하세요. 이후 집계하여 DAY와 TOTAL 단위로 롤업할 수 있습니다.
  • 가능하면 line_items 및 promoted_tweets 수준에서 데이터를 요청하세요. 이후 해당 지표를 집계해 광고 엔티티 계층 전반(예: 캠페인, 자금 조달 수단, 계정 수준)의 합계를 계산할 수 있습니다.
  • 분석 지표 값은 로컬에 저장·보관하세요.
  • 30일보다 오래된 데이터는 반복 조회하지 마세요. 이 데이터는 변경되지 않으므로 로컬에 저장해야 합니다.
  • 모든 비분할 데이터는 실시간이며, 이벤트 발생 후 수초 내에 이용 가능합니다.
  • 전환 지표와 비전환 지표는 요청을 분리해 각각 그룹화하세요.

​
세분화된 데이터 가져오기

  • 위의 “실시간 비세분화 데이터 가져오기” 지침을 참고하세요. 추가 안내는 아래에 제공합니다.
  • 대부분의 세분화 데이터 유형은 경우에 따라 최대 1시간까지 데이터가 완전하지 않을 수 있습니다. INTERESTS로 세분화된 데이터는 최대 12시간까지 지연될 수 있습니다.
  • 해당 정보의 산출 방식상, 세분화 데이터가 비세분화 데이터와 100% 동일하게 합산되지 않을 수 있습니다.

​
과거 데이터 가져오기

  • 데이터 백필(예: 새 광고주 계정을 추가하는 경우)을 할 때는 start_time과 end_time 구간을 더 작게 나눠 여러 번 요청해야 할 수 있습니다.
  • 조회 범위를 30일 단위로 제한하세요.
  • 요청 속도를 조절하고 시간을 두고 분산해, 해당 조회 작업의 요청 한도를 소진하지 않도록 하세요.

​
샘플

이러한 모범 사례 일부를 시연하는 샘플 스크립트(fetch_stats)는 ads-platform-tools GitHub 리포지토리에서 확인하실 수 있습니다.

​
목표별 지표

엔터티에 적용되는 지표는 캠페인 목표에 따라 달라집니다. 이 가이드를 참고해 각 목표 유형별로 가져올 관련 지표 그룹을 파악하고, 추가 파생 지표를 계산하는 방법도 확인하세요.

​
ENGAGEMENTS

관련 지표 그룹: ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 포함된 경우 MEDIA도 해당됩니다.
파생 지표노출된 지표 계산식
참여율engagements/impressions
CPEbilled_charge_local_micro/engagements
미디어 조회율media_views/impressions

​
WEBSITE_CLICKS 및 WEBSITE_CONVERSIONS

관련 메트릭 그룹: ENGAGEMENT, BILLING, 그리고 WEB_CONVERSION. 크리에이티브에 미디어가 사용된 경우 MEDIA도 적용됩니다.
파생 메트릭노출 메트릭 계산식
CPMbilled_charge_local_micro/impressions/1000
클릭률clicks/impressions
CPLCbilled_charge_local_micro/clicks
총 전환 수conversion_custom + conversion_site_visits + conversion_sign_ups + conversion_downloads + conversion_purchases
전환율총 전환 수 / impressions
CPAbilled_charge_local_micro / 총 전환 수

​
APP_INSTALLS 및 APP_ENGAGEMENTS

관련 지표 그룹: ENGAGEMENT, BILLING, MOBILE_CONVERSION, LIFE_TIME_VALUE_MOBILE_CONVERSION. 크리에이티브에서 미디어 또는 비디오 앱 카드가 사용된 경우 MEDIA 및 VIDEO도 해당됩니다.
파생 지표공개 지표 계산식
CPMbilled_charge_local_micro/impressions/1000
앱 클릭률app_clicks/impressions
CPACbilled_charge_local_micro/app_clicks
CPIbilled_charge_local_micro/mobile_conversion_installs

​
FOLLOWERS

관련 지표 그룹: ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 사용된 경우 MEDIA도 해당됩니다.
파생 지표노출 지표 계산식
CPMbilled_charge_local_micro/impressions/1000
팔로우율follows/impressions
CPFbilled_charge_local_micro/follows
미디어 조회율media_views/impressions

​
LEAD_GENERATION

관련 메트릭 그룹: ENGAGEMENT 및 BILLING. 크리에이티브에 미디어가 포함된 경우 MEDIA도 해당됩니다.
파생 메트릭노출 메트릭 계산식
CPMbilled_charge_local_micro/impressions/1000
리드card_engagements
리드율card_engagements/impressions
리드당 비용billed_charge_local_micro/card_engagements

​
VIDEO_VIEWS

관련 메트릭 그룹: ENGAGEMENT, BILLING, VIDEO
파생 메트릭노출 메트릭 계산식
CPMbilled_charge_local_micro/impressions/1000
동영상 조회율video_total_views/impressions
조회당 비용billed_charge_local_micro/video_total_views

​
VIDEO_VIEWS_PREROLL

관련 메트릭 그룹: ENGAGEMENT, BILLING, VIDEO
파생 메트릭공개 메트릭 계산식
CPMbilled_charge_local_micro/impressions/1000
동영상 조회율video_total_views/impressions
조회당 비용(CPV)billed_charge_local_micro/video_total_views

​
지표와 세분화

이 문서는 각 엔터티 유형별로 Analytics에서 제공되는 지표와 각 지표에 적용 가능한 세분화 옵션을 개괄합니다.
지표 그룹
엔터티ENGAGEMENTBILLINGVIDEOMEDIAWEB_CONVERSIONMOBILE_CONVERSIONLIFE_TIME_VALUE_MOBILE_CONVERSION
ACCOUNT✔*
FUNDING_INSTRUMENT✔*✔
CAMPAIGN✔✔✔✔✔✔✔
LINE_ITEM✔✔✔✔✔✔✔
PROMOTED_TWEET✔✔✔✔✔✔✔
MEDIA_CREATIVE✔✔✔✔✔✔✔
ORGANIC_TWEET✔✔
*ENGAGEMENT 지표 그룹의 일부 지표는 계정 및 자금 조달 수단 수준에서 제공되지 않습니다. 자세한 내용은 ENGAGEMENT 섹션을 참조하세요.

​
메트릭 그룹별 사용 가능한 메트릭

​
ENGAGEMENT

Metric설명세분화 가능 여부데이터 유형계정/자금 조달 수단 사용 가능 여부
engagements총 참여 수✔정수 배열✔
impressions총 노출 수✔정수 배열✔
retweets총 리트윗 수✔정수 배열✔
replies총 답글 수✔정수 배열✔
likes총 좋아요 수✔정수 배열✔
follows총 팔로우 수✔정수 배열✔
card_engagements카드 참여 총계✔정수 배열
clicks즐겨찾기 및 기타 참여를 포함한 총 클릭 수✔정수 배열
app_clicks앱 설치 또는 실행 시도 수✔정수 배열
url_clicks광고의 링크 또는 웹사이트 카드에 대한 총 클릭 수(획득 트래픽 포함)✔정수 배열
qualified_impressions유효 노출 총계✔정수 배열
carousel_swipes캐러셀 이미지 또는 동영상에서의 총 스와이프 수✔정수 배열

​
BILLING

지표설명세분화 가능데이터 타입
billed_engagements청구 대상 참여 수 총합✔정수 배열
billed_charge_local_micro마이크로 단위 지역 통화 기준 총 지출액✔정수 배열

​
VIDEO

동영상 메트릭 정의 변경 안내: MRC 표준에 따라 VIDEO 메트릭 그룹의 video_total_views 메트릭은 최소 2초 동안 화면의 50% 이상이 노출된 조회수를 집계합니다. 기존 동영상 조회 정의(최소 3초 동안 100% 화면 노출 기준)는 VIDEO 메트릭 그룹의 새 video_3s100pct_views 메트릭으로 계속 제공됩니다. 기존 정의에 기반해 입찰 및 과금하려면 새로 제공되는 VIEW_3S_100PCT bid_unit을 사용하세요.
메트릭설명세분화 가능 여부데이터 유형
video_total_views총 동영상 조회수✔정수 배열
video_views_25동영상의 최소 25%가 시청된 조회수 합계✔정수 배열
video_views_50동영상의 최소 50%가 시청된 조회수 합계✔정수 배열
video_views_75동영상의 최소 75%가 시청된 조회수 합계✔정수 배열
video_views_100동영상의 100%가 시청된 조회수 합계✔정수 배열
video_cta_clicks콜투액션 클릭 수 합계✔정수 배열
video_content_starts동영상 재생 시작 수 합계✔정수 배열
video_3s100pct_views100% 화면 노출 상태에서 최소 3초 재생된 조회수 합계(레거시 video_total_views)✔정수 배열
video_6s_views동영상의 최소 6초가 시청된 조회수 합계✔정수 배열
video_15s_views동영상의 최소 15초 또는 전체 길이의 95%가 시청된 조회수 합계✔정수 배열

​
MEDIA

MetricDescriptionSegmentation AvailableData Type
media_views동영상, Vine, GIF, 이미지 전반에서 미디어가 자동 재생 또는 클릭으로 조회된 총 횟수.✔정수 배열
media_engagements동영상, Vine, GIF, 이미지 전반에서 미디어가 클릭된 총 횟수.✔정수 배열

​
WEB_CONVERSION

MetricDescriptionSegmentation AvailableData Type
conversion_purchasesPURCHASE 유형의 전환 횟수와 해당 매출 금액 및 주문 수량PLATFORMS onlyJSON object
conversion_sign_upsSIGN_UP 유형의 전환 횟수와 해당 매출 금액 및 주문 수량PLATFORMS onlyJSON object
conversion_site_visitsSITE_VISIT 유형의 전환 횟수와 해당 매출 금액 및 주문 수량PLATFORMS onlyJSON object
conversion_downloadsDOWNLOAD 유형의 전환 횟수와 해당 매출 금액 및 주문 수량PLATFORMS onlyJSON object
conversion_customCUSTOM 유형의 전환 횟수와 해당 매출 금액 및 주문 수량PLATFORMS onlyJSON object

​
MOBILE_CONVERSION

모바일 전환 통계는 MACT가 활성화된 광고주 계정에서만 제공됩니다.
Metric설명세분화 가능 여부데이터 유형
mobile_conversion_spent_creditsSPENT_CREDIT 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_installsINSTALL 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_content_viewsCONTENT_VIEW 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_add_to_wishlistsADD_TO_WISHLIST 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_checkouts_initiatedCHECKOUT_INITIATED 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_reservationsRESERVATION 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_tutorials_completedTUTORIAL_COMPLETED 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_achievements_unlockedACHIEVEMENT_UNLOCKED 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_searchesSEARCH 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_add_to_cartsADD_TO_CART 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_payment_info_additionsPAYMENT_INFO_ADDITION 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_re_engagesRE_ENGAGE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_sharesSHARE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_ratesRATE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_loginsLOGIN 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_updatesUPDATE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_levels_achievedLEVEL_ACHIEVED 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_invitesINVITE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_key_page_viewsKEY_PAGE_VIEW 유형의 모바일 전환을 post_view 및 post_engagement 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_downloadsDOWNLOAD 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_purchasesPURCHASE 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_sign_upsSIGN_UP 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체
mobile_conversion_site_visitsSITE_VISIT 유형의 모바일 전환을 post_view, post_engagement, assisted, order_quantity, sale_amount 기준으로 세분화한 내역✔JSON 객체

​
LIFE_TIME_VALUE_MOBILE_CONVERSION

MACT가 활성화된 광고주 계정에서만 평생 모바일 전환 통계를 사용할 수 있습니다.
MetricDescriptionSegmentation AvailableData Type
mobile_conversion_lifetime_value_purchasesPURCHASE 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_sign_upsSIGN_UP 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_updatesUPDATE 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_tutorials_completedTUTORIAL_COMPLETED 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_reservationsRESERVATION 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_add_to_cartsADD_TO_CART 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_add_to_wishlistsADD_TO_WISHLIST 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_checkouts_initiatedCHECKOUT_INITIATED 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_levels_achievedLEVEL_ACHIEVED 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_achievements_unlockedACHIEVEMENT_UNLOCKED 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_sharesSHARE 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_invitesINVITE 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_payment_info_additionsPAYMENT_INFO_ADDITION 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_spent_creditsSPENT_CREDIT 유형의 모바일 전환 세부 내역JSON object
mobile_conversion_lifetime_value_ratesRATE 유형의 모바일 전환 세부 내역JSON object

​
세분화

세분화 보고를 사용하면 지정된 타깃팅 유형의 값별로 구분된 지표를 조회할 수 있습니다. 세분화는 복잡성이 크게 증가하므로 비동기 분석 쿼리로만 사용할 수 있습니다. 세분화는 MEDIA_CREATIVE 또는 ORGANIC_TWEET 엔터티에서는 지원되지 않습니다. 일부 세분화 유형은 추가 매개변수를 전달해야 합니다. 자세한 내용은 아래를 참고하세요. CITIES 또는 POSTAL_CODES로 세분화할 때 API는 타깃팅된 위치만 반환합니다. Region 및 Metro 세분화는 타깃팅된 위치와 비타깃팅된 위치 모두를 반환합니다.
세분화 유형country 매개변수 필요platform 매개변수 필요
AGE
APP_STORE_CATEGORY
AUDIENCES
CITIES✔
CONVERSATIONS
CONVERSION_TAGS
DEVICES✔
EVENTS
GENDER
INTERESTS
KEYWORDS
LANGUAGES
LOCATIONS
METROS✔
PLATFORMS
PLATFORM_VERSIONS✔
POSTAL_CODES✔
REGIONS✔
SLIDES
SIMILAR_TO_FOLLOWERS_OF_USER
TV_SHOWS

​
파생 지표

캠페인 지표는 캠페인 목표에 따라 달라집니다. 이 가이드를 참고해 현재 설정된 목표에 맞춰 사용할 파생 지표의 계산 방법을 확인하세요. 중괄호가 없는 metric은 Ads API의 analytics 엔드포인트에서 반환되는 지표입니다. 중괄호처럼 보이는 이름({curly brackets})으로 둘러싸인 항목은 해당 범주의 파생 지표를 뜻합니다.

​
참여

파생 지표노출 지표 계산식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Total Engagements}promoted_account_follows + promoted_tweet_search_engagements + promoted_tweet_timeline_engagements + promoted_tweet_profile_engagements 또는 promoted_account_follows + promoted_tweet_search_clicks + promoted_tweet_search_replies + promoted_tweet_search_retweets + promoted_tweet_search_follows + promoted_tweet_timeline_clicks + promoted_tweet_timeline_replies + promoted_tweet_timeline_retweets + promoted_tweet_timeline_follows + promoted_tweet_profile_clicks + promoted_tweet_profile_replies + promoted_tweet_profile_retweets + promoted_tweet_profile_follows
{Engagement Rate}{Total Engagements} / {Impressions}
billed_charge_local_micro / {Total Engagements}
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{Media Views} / {Impressions}

​
WEBSITE_CLICKS

파생 지표노출 지표 계산식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Link Clicks}promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks
{Click Rate}{Link Clicks} / {Impressions}
billed_charge_local_micro / {Link Clicks}
conversion_site_visits
{Conversion Rate}conversion_site_visits / {Impressions}
billed_charge_local_micro / conversion_site_visits

​
APP_INSTALLS 및 APP_ENGAGEMENTS

파생 지표노출 지표 계산식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions
billed_charge_local_micro / {Impressions} / 1000
{App Clicks}promoted_tweet_app_install_attempts + promoted_tweet_app_open_attempts + promoted_tweet_timeline_url_clicks + promoted_tweet_search_url_clicks
{App Click Rate}{App Clicks} / {Impressions}
billed_charge_local_micro / {App Clicks}
billed_charge_local_micro / mobile_conversion_installs

​
팔로워

파생 지표노출 지표 계산 방식
promoted_account_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_account_follows
{Follow Rate}promoted_account_follow_rate
billed_charge_local_micro / promoted_account_follows
{Media Views}promoted_tweet_timeline_media_views + promoted_tweet_search_media_views + promoted_tweet_profile_media_views
{Media View Rate}{Media Views} / {Impressions}

​
LEAD_GENERATION

파생 지표산출 방식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
promoted_tweet_search_card_engagements + promoted_tweet_timeline_card_engagements + promoted_tweet_profile_card_engagements
{Lead Rate}{Leads} / {Impressions}
{Cost Per Lead}billed_charge_local_micro / {Leads}

​
VIDEO_VIEWS

파생 지표노출 지표 산출식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Video Views}promoted_video_total_views
{Video Rate}promoted_video_total_views / {Impressions}
{Cost Per View}billed_charge_local_micro / promoted_video_total_views

​
QUALIFIED_IMPRESSIONS

파생 지표산출 지표 계산식
promoted_tweet_search_impressions + promoted_tweet_timeline_impressions + promoted_tweet_profile_impressions
billed_charge_local_micro / {Impressions} / 1000
{Qualified Impressions}promoted_tweet_timeline_qualified_impressions + promoted_tweet_search_qualified_impressions + promoted_tweet_profile_qualified_impressions
{Qualified Impression Rate}{Qualified Impressions} / {Impressions}
{Cost Per 1000 Qualified Impressions }billed_charge_local_micro / {Qualified Impressions} / 1000

​
사용자 지정

PROMOTED_ACCOUNT의 placement_type에 대해서는 위의 FOLLOWERS 목표를 참조하세요. 이 목표에 해당하는 다른 모든 게재 위치의 경우, 해당 파생 지표는 ENGAGEMENTS를 확인하세요.

​
안내서

​
활성 엔터티

​
소개

Active Entities 엔드포인트는 어떤 캠페인에 대해 애널리틱스를 요청해야 하는지에 대한 정보를 제공하므로, 당사의 동기식 및 비동기식 애널리틱스 엔드포인트와 함께 사용하도록 설계되었습니다. 이 엔드포인트는 광고 엔터티의 세부 정보와 해당 지표가 변경된 시점을 반환합니다. 이 엔드포인트를 사용하면 코드와 애널리틱스 수집 로직을 크게 단순화할 수 있습니다. 이 가이드는 엔드포인트와 해당 데이터 소스에 대한 정보와 컨텍스트를 제공합니다. 또한 사용 지침과 일련의 요청 예시를 통해 애널리틱스 엔드포인트와 함께 Active Entities를 사용하는 방법을 보여줍니다. 요약에서는 권장 접근 방식에 대한 상위 수준의 설명을 제공합니다.

​
데이터

광고 엔터티의 지표가 변경될 때마다 해당 변경 사항을 기록합니다. 이러한 변경 이벤트는 시간 단위 버킷에 저장되며, 엔터티 관련 세부 정보와 변경이 적용되는 시점에 대한 정보를 포함합니다. 후자는 변경 이벤트가 항상 기록된 시점과 일치하지 않을 수 있기 때문에 필요합니다. 청구 조정이 흔한 이유이지만, 다른 경우도 있습니다.

​
엔드포인트

​
요청

Active Entities 요청은 광고 계정 범위에서 수행되며, 세 가지 필수 쿼리 매개변수 entity, start_time, end_time가 필요합니다. twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z" 지원되는 entity 값은 CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET입니다. 이는 애널리틱스 엔드포인트가 지원하는 엔터티 유형을 반영합니다. start_time과 end_time 값은 ISO 8601 형식으로 지정해야 하며, 조회할 시간별 버킷을 명시합니다. 두 값 모두 정시 단위로만 표현되어야 합니다. 이 엔드포인트는 결과 필터링에 사용할 수 있는 선택적 매개변수 funding_instrument_ids, campaign_ids, line_item_ids도 지원합니다. 이는 광고 계층의 모든 수준에서, 지정한 어떤 entity 유형과도 함께 작동합니다.

​
응답

위 요청에 대한 Active Entities 응답은 아래에 표시되어 있습니다. 
    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-03-05T00:00:00Z",
          "end_time": "2019-03-06T00:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2r0wxw",
          "activity_start_time": "2019-03-04T20:55:20Z",
          "activity_end_time": "2019-03-05T03:43:56Z",
          "placements": [
            "ALL_ON_TWITTER",
          ]
        },
        {
          "entity_id": "2r30fn",
          "activity_start_time": "2019-03-05T08:11:08Z",
          "activity_end_time": "2019-03-05T14:40:59Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }
data 배열에는 이후 애널리틱스 요청에 포함해야 하는 각 엔터티별 객체가 들어 있습니다. 이 집합에 없는 ID에 대해서는 애널리틱스를 요청하지 마세요. 각 객체에는 네 가지 필드가 있습니다: entity_id, activity_start_time, activity_end_time, placements. 활동 시작 및 종료 시간은 해당 엔터티의 변경 이벤트가 적용되는 기간을 의미하며, 이에 따라 이후 애널리틱스 요청에서 지정해야 할 날짜가 결정됩니다. placements 배열에는 ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND 값을 포함할 수 있습니다. 이는 해당 엔터티 ID에 대해 어떤 노출 위치를 요청해야 하는지를 나타냅니다.

​
사용

Active Entities 엔드포인트는 분석 요청 방식을 결정하는 기준이 됩니다. 아래 사용 지침은 분석 동기화를 지원하기 위해 작성되었으며, 파트너가 Twitter와 데이터 저장소를 동기화 상태로 유지하도록 돕습니다. 즉, 정기적으로 예약된 백그라운드 동기화를 수행하는 방법을 설명합니다. 개발자가 내려야 할 결정은 두 가지입니다.
  1. 활성 엔터티 정보를 얼마나 자주 요청할지, 그리고 이에 따라 분석 데이터를 얼마나 자주 끌어올지.
  2. 활동 시작 및 종료 시간을 사용해 분석 요청의 start_time 및 end_time 값을 어떻게 결정할지.
이 내용은 요약 이후 아래의 두 개 하위 섹션에서 더 자세히 설명합니다.

​
요약

다음과 같은 방식으로 Active Entities 엔드포인트를 사용해 애널리틱스 요청 방식을 정합니다. 활성 엔터티 정보를 얼마나 자주 요청할지, 즉 애널리틱스를 얼마나 자주 수집할지 결정한 뒤에 아래 절차를 따르세요.
  1. Active Entities 요청을 보냅니다.
  2. 응답을 placement별로 나눕니다. ALL_ON_TWITTER용 그룹 하나, PUBLISHER_NETWORK용 하나, SPOTLIGHT용 하나, TREND용 하나를 만듭니다.
  3. 각 placement 그룹에 대해 다음을 수행합니다.
    1. 엔터티 ID를 추출합니다.
    2. 애널리틱스 start_time 및 end_time 값을 정합니다.
      • 최소 activity_start_time을 찾고, 이 값을 내림합니다.
      • 최대 activity_end_time을 찾고, 이 값을 올림합니다.
    3. 애널리틱스 요청을 보냅니다.
      • 엔터티 ID를 20개씩 배치로 묶습니다.
      • 3-b에서 구한 start_time과 end_time 값을 사용합니다.
      • 적절한 placement 값을 지정합니다.
    4. 데이터 저장소에 저장합니다.
Python SDK 사용 예시는 active_entities.py를 참고하세요.

​
빈도

첫 번째 질문에 대한 답은 Active Entities 요청에 사용해야 할 시간 범위를 결정합니다. 예를 들어 매시간 활성 엔티티 정보를 요청한다면 시간 범위는 1시간이어야 합니다. 하루에 한 번 활성 엔티티 정보를 요청한다면 시간 범위는 하루여야 합니다. 즉, 현재 요청의 start_time이 직전 요청의 end_time과 같도록 시간 범위를 선택해야 합니다.
참고: 하나의 시간 구간은 한 번만 요청해야 합니다. 동일한 시간 구간을 두 번 이상 요청하면 불필요한 분석 요청이 발생합니다. (아래 예외 참조.)
파트너가 현재 시간에 대해 한 시간 동안 여러 차례 분석을 요청하려는 경우에도 동일한 패턴이 적용됩니다. 즉, 요청 빈도가 시간 범위를 결정합니다. 아래 표는 이 시나리오에 대한 Active Entities의 시작 및 종료 타임스탬프 예시를 보여줍니다.
요청 시각start_time 타임스탬프end_time 타임스탬프
00:15:0000:00:0000:15:00
00:30:0000:15:0000:30:00
00:45:0000:30:0000:45:00
01:00:0000:45:0001:00:00
변경 이벤트의 저장 방식으로 인해 위의 네 가지 Active Entities 요청은 모두 동일한 시간별 버킷을 조회하며, 이는 이 사용 사례에 필요합니다. 다만 현재 시간이 지나면 해당 시간별 버킷은 더 이상 조회하지 않아야 합니다.

​
활동 시간

활동 시작 및 종료 시간을 다룰 때는 다음과 같은 방식을 권장합니다. Active Entities 응답의 모든 객체에서 최소 activity_start_time과 최대 activity_end_time을 찾습니다. 최소 활동 시작 시간은 내림하고 최대 활동 종료 시간은 올림하여 값을 조정합니다. 구체적으로 둘 다 시각을 0으로 설정하고 종료 시간에는 하루를 추가합니다. 아래 표에 예시가 나와 있습니다. 이렇게 산출된 시작 및 종료 시간을 이후 분석 요청에 지정해야 합니다.
최소, 최대 활동 시간산출된 시간
2019-03-04T20:55:20Z

2019-03-05T14:40:59Z		2019-03-04T00:00:00Z

2019-03-06T00:00:00Z
참고: 시, 분, 초가 0으로 설정된 타임스탬프를 포함하는 것이 중요합니다. 그렇지 않고 날짜만 전달되면, 광고 계정의 표준시대에서 자정에 시작해 자정에 종료되는 분석을 요청한 것으로 간주되며, 이는 바람직하지 않을 수 있습니다. 예를 들어 최소 활동 시작 시간이 2019-02-28T01:30:07Z이고 오프셋이 -08:00:00인 광고 계정에서 타임스탬프를 생략하면, 분석 요청은 01:30부터 08:00 사이에 발생한 변경 사항을 놓치게 됩니다. 또는 하루 단위로 확장하지 않고 반환된 활동 시간 창에 대해서만 분석을 요청할 수도 있습니다. 이 방식을 사용할 경우 산출된 시작 및 종료 시간은 각각 2019-03-04T20:00:00Z와 2019-03-05T15:00:00Z가 됩니다. (분석 요청에서 DAY 세분성을 지정한 경우 이러한 범위는 허용되지 않습니다.)

​
예시

이 섹션은 동기식 애널리틱스 엔드포인트와 함께 Active Entities를 사용하는 방법을 보여줍니다. (가독성을 위해 응답을 일부 수정했습니다.) 이 예시에서는 매 정시마다 Active Entities 엔드포인트를 호출하며, 각 요청은 직전 1시간을 조회합니다. 응답에 따라 동기식 애널리틱스 엔드포인트의 사용 방식이 결정됩니다. 첫 번째 Active Entities 요청은 03:00:00에 수행됩니다. 응답은 line item dvcz7의 지표가 변경되었고, 해당 변경 이벤트가 02:02:55부터 02:28:12 사이의 기간에 적용됨을 나타냅니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:02:55Z",
          "activity_end_time": "2019-02-11T02:58:12Z",
          "placements": [
            "트위터 전반"
          ]
        }
      ]
    }
위의 접근 방식을 적용하고 해당 활동의 시작 및 종료 시간을 기준으로, 분석용 start_time과 end_time 값은 각각 2019-02-11T00:00:00Z와 2019-02-12T00:00:00Z로 설정됩니다. 활성 엔터티 정보를 바탕으로 예상한 대로, 아래 각 메트릭 배열의 세 번째 요소가 0이 아님을 확인할 수 있습니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
다음 Active Entities 요청은 04:00:00에 수행되며 직전 한 시간만 확인합니다. 앞서 언급했듯이 시간 구간은 한 번만 요청해야 합니다. 응답을 보면 이 라인 아이템의 변경 이벤트가 02:00:00과 03:00:00 모두에 적용됨을 알 수 있습니다. 이어지는 애널리틱스 요청에서는 두 시간 모두에 대한 변경 사항이 표시될 것으로 예상합니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T02:07:17Z",
          "activity_end_time": "2019-02-11T03:49:22Z",
          "placements": [
            "트위터 전체"
          ]
        }
      ]
    }
03:00:00에 0이 아닌 지표가 표시되는 것 외에도 노출수, 지출액, MRC 동영상 조회수가 이전 값에서 업데이트된 것을 확인할 수 있습니다. 예를 들어 노출수는 02:00:00 시간대에 2,995로, 이전 2,792에서 증가했습니다. 이는 03:00:00 시간대에 기록된 변경 이벤트가 02:00:00 시간대에 어떻게 적용되는지를 보여줍니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
05:00:00의 Active Entities 요청에서도 바로 이전 한 시간만을 살펴보면, 변경 이벤트가 03:00:00 시간대에만 적용된다는 점을 보여줍니다. 이어지는 요청의 애널리틱스 지표 변경 내용도 이를 반영합니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"`

    {
      "request": {},
      "data": [
        {
          "entity_id": "dvcz7",
          "activity_start_time": "2019-02-11T03:42:39Z",
          "activity_end_time": "2019-02-11T03:48:48Z",
          "placements": [
            "ALL_ON_TWITTER"
          ]
        }
      ]
    }
애널리틱스 응답에 따르면 03:00:00 시각의 지표만 변경되었고, 02:00:00 시각의 값은 이전 애널리틱스 요청 때와 동일합니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"`

    {
      "data_type": "stats",
      "time_series_length": 24,
      "data": [
        {
          "id": "dvcz7",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "engagements": [
                  0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ],
                "video_total_views": [
                  0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
                ]
              }
            }
          ]
        }
      ],
      "request": {}
    }
마지막으로 06:00:00에는 추가 변경 이벤트가 없음을 확인합니다. 참고: 그렇다고 해서 이 라인 아이템의 지표가 향후 변경될 수 없다는 뜻은 아닙니다. 
`twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"`

    {
      "request": {},
      "data": []
    }

​
비동기 안내서

​
API 레퍼런스

​
비동기식 애널리틱스

​
소개

비동기 분석 엔드포인트는 파트너와 광고주가 생성 요청을 제출하면 서버가 이를 비동기적으로 처리하여 지표를 조회할 수 있도록 합니다. (이를 비동기 분석 ‘작업’이라고 부릅니다.) 이 방식에서는 요청이 완료될 때까지 클라이언트 연결을 유지할 필요가 없습니다. 이러한 엔드포인트는 동기식 엔드포인트와 마찬가지로 파트너와 광고주가 캠페인 실적에 대한 상세 통계를 요청할 수 있게 합니다. 계정, 자금 조달 수단, 캠페인, 라인 아이템, 프로모트된 트윗, 미디어 크리에이티브에 대한 데이터 요청을 지원합니다. 동기식 엔드포인트와의 차이는 비동기 분석 엔드포인트가 최대 90일에 이르는 더 긴 기간과 세분화를 지원한다는 점입니다. 두 방식의 차이에 대한 자세한 내용은 Analytics Overview 페이지에서 확인할 수 있습니다. 동기식 엔드포인트와 달리, 속도 제한은 특정 계정의 동시 작업 수를 기준으로 적용됩니다. 즉, 특정 시점에 처리 상태에 있을 수 있는 작업 수에 따라 결정되며, 이는 광고 계정 수준에서 집계됩니다.

​
사용 방법

비동기 분석 엔드포인트를 사용해 캠페인 지표를 가져오는 과정은 여러 단계로 구성됩니다. 작업을 생성하고, 작업 처리 완료 여부를 확인한 다음, 데이터를 다운로드합니다. 데이터 파일은 압축을 해제해야 합니다. 네 가지 구체적인 단계는 아래와 같습니다.
  1. POST stats/jobs/accounts/:95 엔드포인트를 사용하여 작업을 생성합니다.
  2. 작업 처리 완료 여부를 확인하기 위해 일정한 간격으로 GET stats/jobs/accounts/:95 엔드포인트에 요청을 보냅니다.
  3. 작업 처리가 완료되면 데이터 파일을 다운로드합니다.
  4. 데이터 파일의 압축을 해제합니다.
데이터 파일에 포함된 응답 오브젝트는 동기식 분석 엔드포인트의 응답과 동일한 JSON 스키마를 따릅니다. 세분화된 캠페인 지표는 비동기 분석 엔드포인트를 통해서만 제공됩니다. 캠페인 지표는 지역, 성별, 관심사, 키워드 등으로 분류할 수 있습니다. 전체 옵션 목록은 Metrics and Segmentation 페이지를 참조하세요. 세분화된 지표를 요청하려면 작업을 생성할 때 segmentation_type 요청 매개변수를 사용하세요.

​
예시

이 섹션에서는 비동기 분석 엔드포인트 사용 방법을 설명합니다. POST stats/jobs/accounts/:account_id 엔드포인트로 작업 생성을 먼저 수행하세요. 아래 예시는 특정 라인 아이템에 대해 일주일 동안 노출 수, 좋아요, 클릭 등 참여 지표를 요청합니다. (요청한 시간 범위는 타임스탬프가 자정으로 설정되어 있으므로 3월 20일은 포함되지 않습니다.) 
$ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT"

    {
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      },
      "data": {
        "start_time": "2019-03-12T00:00:00Z",
        "segmentation_type": null,
        "url": null,
        "id_str": "1120829647711653888",
        "entity_ids": [
          "el32n"
        ],
        "end_time": "2019-03-20T00:00:00Z",
        "country": null,
        "placement": "ALL_ON_TWITTER",
        "id": 1120829647711653888,
        "expires_at": null,
        "account_id": "18ce54d4x5t",
        "status": "PROCESSING",
        "granularity": "TOTAL",
        "entity": "LINE_ITEM",
        "created_at": "2019-04-23T23:19:46Z",
        "platform": null,
        "updated_at": "2019-04-23T23:19:46Z",
        "metric_groups": [
            "ENGAGEMENT"
        ]
      }
    }
이 응답은 라인 아이템 메트릭을 반환하지 않습니다. 방금 생성한 작업에 대한 정보만 제공합니다. 작업 상태를 확인하려면 작업 ID가 필요합니다. 이는 id와 id_str 응답 속성 모두에 표시됩니다. 다음으로, 이전 응답의 id_str를 사용해 생성한 작업이 응답에서 "status": "SUCCESS"로 표시되듯 처리 완료되었는지 확인해야 합니다. 이는 데이터가 다운로드할 준비가 되었음을 의미합니다. url 필드에는 다운로드 링크가 포함됩니다. 
$ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888"

    {
      "request": {
        "params": {
          "job_ids": [
            1120829647711653888
          ]
        }
      },
      "next_cursor": "1120828505715920896",
      "data": [
        {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz",
          "id_str": "1120829647711653888",
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "X 전체",
          "id": 1120829647711653900,
          "expires_at": "2019-04-25T23:19:48Z",
          "account_id": "18ce54d4x5t",
          "status": "성공",
          "granularity": "총합",
          "entity": "라인 아이템",
          "created_at": "2019-04-23T23:19:46Z",
          "platform": null,
          "updated_at": "2019-04-23T23:19:48Z",
          "metric_groups": [
            "참여"
          ]
        }
      ]
    }
위 예시에서는 단일 작업 ID를 전달했지만, 실제로는 한 번에 여러 작업의 상태를 확인할 수 있도록 최대 200개의 작업 ID를 지정해 job_ids 매개변수를 사용하는 것이 좋습니다. 다음으로, 표시된 url 값으로 데이터 파일을 다운로드하세요. 
    $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    --2019-04-23 17:52:12--  https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz
    ton.twimg.com(ton.twimg.com) 해석 중... 72.21.91.70
    ton.twimg.com(ton.twimg.com)|72.21.91.70|:443에 연결 중... 연결됨.
    HTTP 요청 전송, 응답 대기 중... 200 OK
    길이: 381 [application/gzip]
    저장: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz'

    zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>]     381  --.-KB/s    in 0s

    2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' 저장됨 [381/381]
마지막으로 파일의 압축을 풀세요. 
`$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz`
파일 내용은 아래에 표시됩니다. 
`$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json`

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "el32n",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  3482
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": [
                  102
                ],
                "unfollows": null,
                "likes": [
                  15
                ],
                "engagements": [
                  171
                ],
                "clicks": [
                  30
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2019-03-12T00:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "el32n"
          ],
          "end_time": "2019-03-20T00:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
도달률 및 평균 노출 빈도

​
GET stats/accounts/:account_id/reach/campaigns

지정한 캠페인의 도달 범위와 평균 노출 빈도 지표를 조회합니다.

​
리소스 URL

https://ads-api.x.com/stats/accounts/:95/reach/campaigns

​
매개변수

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

Type: string

Example: 18ce54d4x5t
campaign_ids
required		쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 캠페인으로만 제한합니다. 최대 20개의 ID를 제공할 수 있습니다.

Note: 최대 20개의 캠페인 ID를 제공할 수 있습니다.

Type: string

Example: 8fgzf
end_time
required		가져올 데이터를 ISO 8601 형식으로 표현된 지정된 종료 시각으로 한정합니다.

Note: 정시(분 0, 초 0)로 표현해야 합니다.

Type: string

Example: 2017-05-26T07:00:00Z
start_time
required		가져올 데이터를 ISO 8601 형식으로 표현된 지정된 시작 시각으로 한정합니다.

Note: 정시(분 0, 초 0)로 표현해야 합니다.

Type: string

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

​
예제 요청

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

​
예제 응답

    {
      "request": {
        "params": {
          "campaign_ids": [
            "8fgzf"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "8fgzf",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​
GET stats/accounts/:account_id/reach/funding_instruments

지정된 펀딩 인스트루먼트에 대한 도달률(reach) 및 평균 노출 빈도(average frequency) 분석을 조회합니다.

​
리소스 URL

https://ads-api.x.com/stats/accounts/:95/reach/funding_instruments

​
매개변수

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

유형: string

예시: 18ce54d4x5t
funding_instrument_ids
required		쉼표로 구분된 식별자 목록을 지정하여 응답을 원하는 결제 수단으로만 제한합니다. 최대 20개의 ID를 제공할 수 있습니다.

참고: 결제 수단 ID는 최대 20개까지 제공할 수 있습니다.

유형: string

예시: lygyi
end_time
required		ISO 8601 형식의 종료 시간으로 조회 데이터를 제한합니다.

참고: 반드시 정시(분 0, 초 0)로 표기해야 합니다.

유형: string

예시: 2017-05-26T07:00:00Z
start_time
required		ISO 8601 형식의 시작 시간으로 조회 데이터를 제한합니다.

참고: 반드시 정시(분 0, 초 0)로 표기해야 합니다.

유형: string

예시: 2017-05-19T07:00:00Z

​
예제 요청

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26

​
예시 응답

    {
      "request": {
        "params": {
          "funding_instrument_ids": [
            "lygyi"
          ],
          "start_time": "2017-05-19T00:00:00Z",
          "end_time": "2017-05-26T00:00:00Z",
          "account_id": "18ce54d4x5t"
        }
      },
      "data_type": "reach",
      "data": [
        {
          "id": "lygyi",
          "total_audience_reach": 1217,
          "average_frequency": 1.01
        }
      ]
    }

​
동기식 분석

​
GET stats/accounts/:account_id

현재 계정의 동기식 분석 데이터를 조회합니다. 허용되는 최대 시간 범위(end_time - start_time)는 7일입니다.

​
리소스 URL

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

​
매개변수

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

유형: string

예시: 18ce54d4x5t
end_time
필수		ISO 8601로 표현한 지정된 종료 시점으로 조회 데이터를 제한합니다.

참고: 반드시 정시(분 0, 초 0)로 표현해야 합니다.

유형: string

예시: 2017-05-26T07:00:00Z
entity
필수		데이터를 조회할 엔터티 유형입니다.

유형: enum

가능한 값: ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, ORGANIC_TWEET, PROMOTED_ACCOUNT, PROMOTED_TWEET, MEDIA_CREATIVE
entity_ids
필수		데이터를 조회할 특정 엔터티입니다. 쉼표로 구분한 엔터티 ID 목록을 지정합니다.

참고: 최대 20개의 엔터티 ID를 제공할 수 있습니다.

유형: string

예시: 8u94t
granularity
필수		조회 데이터의 세분화 수준을 지정합니다.

유형: enum

가능한 값: DAY, HOUR, TOTAL
metric_groups
필수		반환할 메트릭 그룹입니다. 쉼표로 구분한 메트릭 그룹 목록을 지정합니다. 자세한 내용은 Metrics and Segmentation을 참조하세요.

참고: MOBILE_CONVERSION 데이터는 별도로 요청해야 합니다.

유형: enum

가능한 값: BILLING, ENGAGEMENT, LIFE_TIME_VALUE_MOBILE_CONVERSION, MEDIA, MOBILE_CONVERSION, VIDEO, WEB_CONVERSION
placement
필수		조회 데이터를 특정 게재 위치로 제한합니다.

참고: 요청당 하나의 값만 허용됩니다. X와 X Audience Platform 모두에 게재되는 엔터티의 경우 게재 위치 값별로 각각 별도의 요청이 필요합니다.

유형: enum

가능한 값: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT, TREND
start_time
필수		ISO 8601로 표현한 지정된 시작 시점으로 조회 데이터를 제한합니다.

참고: 반드시 정시(분 0, 초 0)로 표현해야 합니다.

유형: string

예시: 2017-05-19T07:00:00Z

​
예시 요청

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

​
예시 응답

    {
      "data_type": "stats",
      "time_series_length": 1,
      "data": [
        {
          "id": "8u94t",
          "id_data": [
            {
              "segment": null,
              "metrics": {
                "impressions": [
                  1233
                ],
                "tweets_send": null,
                "qualified_impressions": null,
                "follows": null,
                "app_clicks": null,
                "retweets": null,
                "likes": [
                  1
                ],
                "engagements": [
                  58
                ],
                "clicks": [
                  58
                ],
                "card_engagements": null,
                "poll_card_vote": null,
                "replies": null,
                "carousel_swipes": null
              }
            }
          ]
        }
      ],
      "request": {
        "params": {
          "start_time": "2017-05-19T07:00:00Z",
          "segmentation_type": null,
          "entity_ids": [
            "8u94t"
          ],
          "end_time": "2017-05-26T07:00:00Z",
          "country": null,
          "placement": "ALL_ON_TWITTER",
          "granularity": "TOTAL",
          "entity": "LINE_ITEM",
          "platform": null,
          "metric_groups": [
            "ENGAGEMENT"
          ]
        }
      }
    }

​
활성 엔터티

​
GET stats/accounts/:account_id/active_entities

지정된 기간 동안 어떤 엔터티의 애널리틱스 지표가 변경되었는지에 대한 세부 정보를 가져옵니다. 이 엔드포인트는 당사의 애널리틱스 엔드포인트와 함께 사용해야 합니다. 이 엔드포인트의 결과는 어떤 광고 엔터티에 대해 애널리틱스를 요청해야 하는지 보여줍니다. 사용 지침은 Active Entities 가이드를 참조하세요. 변경 이벤트는 시간 단위 버킷으로 제공됩니다.
  • start_time 및 end_time 값은 조회할 시간 단위 버킷을 지정합니다.
  • 반환되는 data 배열에는 이후 애널리틱스 요청에 포함해야 하는 각 엔터티의 객체가 포함됩니다.
  • 중요: 이후 애널리틱스 요청에서 지정해야 하는 날짜는 activity_start_time 및 activity_end_time 값을 기준으로 결정해야 합니다.
    • 이 값은 저장된 변경 이벤트가 적용되는 시간 범위를 나타냅니다. 이는 엔터티별로 반환됩니다.
참고: 허용되는 최대 시간 범위(end_time - start_time)는 90일입니다.

​
리소스 URL

https://ads-api.x.com/12/stats/accounts/:95/active_entities

​
Parameters

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

Type: string

Example: 18ce54d4x5t
end_time
required		조회된 데이터의 범위를 ISO 8601로 표현된 지정 종료 시각으로 제한합니다.

Note: 반드시 정시(분 0, 초 0)로 표현해야 합니다.

Type: string

Example: 2017-05-26T07:00:00Z
entity
required		데이터를 조회할 엔터티 유형입니다.

Type: enum

Possible values: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT, PROMOTED_TWEET
start_time
required		조회된 데이터의 범위를 ISO 8601로 표현된 지정 시작 시각으로 제한합니다.

Note: 반드시 정시(분 0, 초 0)로 표현해야 합니다.

Type: string

Example: 2017-05-19T07:00:00Z
campaign_ids
optional		쉼표로 구분된 식별자 목록을 지정하여, 원하는 캠페인과 연관된 엔터티로만 응답을 제한합니다. 최대 200개의 ID를 제공할 수 있습니다.

Note: funding_instrument_ids 및 line_item_ids와 상호 배타적입니다.

Type: string

Example: 8wku2
funding_instrument_ids
optional		쉼표로 구분된 식별자 목록을 지정하여, 원하는 자금 조달 수단과 연관된 엔터티로만 응답을 제한합니다. 최대 200개의 ID를 제공할 수 있습니다.

Note: campaign_ids 및 line_item_ids와 상호 배타적입니다.

Type: string

Example: lygyi
line_item_ids
optional		쉼표로 구분된 식별자 목록을 지정하여, 원하는 라인 아이템과 연관된 엔터티로만 응답을 제한합니다. 최대 200개의 ID를 제공할 수 있습니다.

Note: campaign_ids 및 line_item_ids와 상호 배타적입니다.

Type: string

Example: 8v7jo

​
예제 요청

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

​
예시 응답

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "PROMOTED_TWEET",
          "start_time": "2019-02-28T08:00:00Z",
          "end_time": "2019-03-01T08:00:00Z"
        }
      },
      "data": [
        {
          "entity_id": "2mvb28",
          "activity_start_time": "2019-02-28T01:30:07Z",
          "activity_end_time": "2019-03-01T07:42:55Z",
          "placements": [
            "ALL_ON_TWITTER",
          ]
        },
        {
          "entity_id": "2mvb29",
          "activity_start_time": "2019-02-27T11:30:07Z",
          "activity_end_time": "2019-03-01T07:42:50Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK",
          ]
        },
        {
          "entity_id": "2mvfan",
          "activity_start_time": "2019-02-27T09:00:05Z",
          "activity_end_time": "2019-03-01T06:06:36Z",
          "placements": [
            "PUBLISHER_NETWORK",
          ]
        },
        {
          "entity_id": "2n17dx",
          "activity_start_time": "2019-02-28T02:02:26Z",
          "activity_end_time": "2019-03-01T07:52:44Z",
          "placements": [
            "ALL_ON_TWITTER",
            "PUBLISHER_NETWORK"
          ]
        }
      ]
    }