메인 콘텐츠로 건너뛰기

​
개요

metrics 필드를 사용하면 개발자가 게시물 및 미디어 객체의 공개 및 비공개 참여 지표에 액세스할 수 있습니다. 공개 지표는 개발자 계정이 있는 누구나 액세스할 수 있으며, 비공개 지표는 소유/승인된 계정(아래 정의)에서 액세스할 수 있습니다. 지표에는 요청에 지정된 각 게시물에 대한 노출 수, 리트윗, 인용 리트윗, 좋아요, 답글, 동영상 조회수, 동영상 조회 구간(사분위), URL 및 프로필 링크 클릭의 총합이 포함됩니다. 게시물이 Ad로 프로모션된 경우, 오가닉 또는 프로모션 컨텍스트에서 획득한 지표의 세부 내역을 확인하는 옵션도 제공합니다. 공개 지표는 App-only Token 인증으로 요청할 수 있습니다. 비공개 지표는 소유/승인된 게시물에 대해서만 요청할 수 있으므로, 개발자는 OAuth 2.0 또는 OAuth 1.0a 사용자 컨텍스트 인가로 인증해야 합니다. 비공개, 오가닉, 프로모션 지표는 최근 30일 내에 생성된 게시물에만 제공됩니다.

​
용어

  • Authorized account: 해당 계정에 대한 액세스 권한을 부여해 X developer app을 승인한 X 계정(어떤 app permission level이든 게시물 지표에 대한 접근을 허용).
  • Owned account: 사용자의 X developer app과 연결된 X 계정.
  • Public metrics: 좋아요 수, 리포스트 수 등 X에서 누구나 확인할 수 있는 합계.
  • Non-public metrics: 노출 수 및 동영상 조회 사분위수 등 X에서 공개적으로 볼 수 없는 합계. OAuth 2.0 또는 OAuth 1.0a 사용자 컨텍스트 인증이 필요.
  • Organic metrics: 오가닉 컨텍스트(일반적인 방식으로 게시되고 조회됨)에 귀속되는 공개 및 비공개 지표 묶음. OAuth 2.0 또는 OAuth 1.0a 사용자 컨텍스트 인증이 필요.
  • Promoted metrics: 프로모션 컨텍스트(Ads 캠페인의 일부로 게시되거나 조회됨)에 귀속되는 공개 및 비공개 지표 묶음. OAuth 2.0 또는 OAuth 1.0a 사용자 컨텍스트 인증이 필요하며, 해당 게시물이 광고에서 프로모션된 경우에 한함.

​
사용 가능한 메트릭

MetricAPI RepresentationsDescription
Impressionsdata.non_public_metrics.impression_count, data.organic_metrics.impression_count, data.promoted_metrics.impression_count게시물이 화면에 표시된 총 횟수(사용자 기준 고유값 아님). 게시물의 일부라도 화면에 보이면 조회로 계산됩니다. OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다.
Retweetsdata.public_metrics.retweet_count, data.organic_metrics.retweet_count, data.promoted_metrics.retweet_count게시물이 리트윗된 횟수. 인용 트윗(“댓글이 있는 리트윗”)은 포함되지 않습니다. X 클라이언트에 표시되는 “리트윗 및 댓글” 합계를 얻으려면 retweet_count와 quote_count를 합산하세요.
Quote Tweetsdata.public_metrics.quote_count게시물이 새 댓글(메시지)과 함께 리트윗된 횟수. 유료 컨텍스트에서 발생한 인용 트윗은 없으므로 모든 인용 트윗은 오가닉입니다.
Likesdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_count게시물에 대한 좋아요 횟수. public_metrics 필드는 X에 공개적으로 표시되는 집계와의 일관성을 위해 오가닉과 유료 컨텍스트의 좋아요를 합산한 총계를 반환합니다.
Repliesdata.public_metrics.reply_count, data.organic_metrics.reply_count, data.promoted_metrics.reply_count게시물에 대한 답글 횟수. public_metrics 필드는 오가닉과 유료 컨텍스트의 답글을 합산한 총계를 반환합니다.
URL Link Clicksdata.non_public_metrics.url_link_clicks, data.organic_metrics.url_link_clicks, data.promoted_metrics.url_link_clicks사용자가 게시물의 URL 링크 또는 URL 미리보기 카드를 클릭한 횟수. OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다.
User Profile Clicksdata.non_public_metrics.user_profile_clicks, data.organic_metrics.user_profile_clicks, data.promoted_metrics.user_profile_clicks사용자가 게시물의 일부(표시 이름, 사용자 이름, 프로필 사진)를 클릭한 횟수. OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다.
Video viewsincludes.media.public_metrics.view_count, includes.media.organic_metrics.view_count, includes.media.promoted_metrics.view_count게시물에 포함된 동영상이 시청된 횟수. 이는 해당 동영상이 게시된 모든 게시물에서 집계된 동영상 조회수입니다. 미디어 확장 expansions=attachment.media_keys가 필요합니다.
Video view quartilesincludes.media.non_public_metrics.playback_0_count, includes.media.non_public_metrics.playback_25_count, includes.media.non_public_metrics.playback_50_count, includes.media.non_public_metrics.playback_75_count, includes.media.non_public_metrics.playback_100_count동영상에서 각 사분위 구간까지 재생을 완료한 사용자 수. OAuth 1.0a 사용자 컨텍스트 인증과 미디어 확장 expansions=attachment.media_keys가 필요합니다.

​
메트릭 요청

​
공개 지표

다음 요청에서는 게시물과 첨부된 동영상의 공개 지표를 아래 필드와 expansions로 요청합니다. $BEARER_TOKEN을(를) 본인이 생성한 베어러 토큰으로 교체하세요.
  • tweet.fields=public_metrics
  • expansions=attachments.media_keys&media.fields=public_metrics

​
예시 요청

curl 'https://api.x.com/2/tweets?ids=1204084171334832128&tweet.fields=public_metrics&expansions=attachments.media_keys&media.fields=public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'

​
비공개 메트릭(비공개, 오가닉 메트릭)

다음 요청은 게시물과 첨부된 동영상에 대해 오가닉 메트릭의 추가 세부 정보와 함께 비공개 메트릭을 조회합니다. 이러한 필드는 비공개이며 X에서 일반에 공개되지 않으므로, 요청에는 OAuth 2.0 또는 OAuth 1.0a 사용자 컨텍스트 인증이 필요합니다. 아래에 필요한 OAuth 1.0a 서명 생성 방법은 가이드를 참고하세요.
  • tweet.fields=non_public_metrics,organic_metrics
  • expansions=attachments.media_keys&media.fields=non_public_metrics,organic_metrics

​
요청 예시

curl 'https://api.x.com/2/tweets/1204084171334832128?tweet.fields=non_public_metrics,organic_metrics&media.fields=non_public_metrics,organic_metrics&expansions=attachments.media_keys' --header 'authorization: OAuth oauth_consumer_key="CONSUMER_API_KEY", oauth_nonce="OAUTH_NONCE", oauth_signature="OAUTH_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="OAUTH_TIMESTAMP", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​
응답 예시

{
  "data": {
    "attachments": {
      "media_keys": ["13_1204080851740315648"]
    },
    "id": "1263145271946551300",
    "non_public_metrics": {
      "impression_count": 956,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "organic_metrics": {
      "impression_count": 956,
      "like_count": 49,
      "reply_count": 2,
      "retweet_count": 9,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "text": "test"
  },
  "includes": {
    "media": [
      {
        "media_key": "13_1204080851740315648",
        "non_public_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1
        },
        "organic_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1,
          "view_count": 1
        },
        "type": "video"
      }
    ]
  }
}