메인 콘텐츠로 건너뛰기
X API는 게시물과 미디어에 대한 참여 지표를 제공합니다. 모든 인증 방식으로 공개 지표에 접근할 수 있으며, 사용자 인증을 사용하면 자신의 콘텐츠에 대한 비공개 지표에 접근할 수 있습니다.

​
메트릭 유형

TypeAuthenticationDescription
PublicBearer Token모든 사용자에게 보이는 메트릭 (좋아요, 리포스트, 답글 등)
Non-publicUser context비공개 메트릭 (노출 수, 클릭 수 등)
OrganicUser context프로모션되지 않은 조회에서 발생한 메트릭
PromotedUser context광고 조회에서 발생한 메트릭
30일 제한: Non-public, Organic, Promoted 메트릭은 최근 30일 이내에 생성된 포스트에 대해서만 제공됩니다.

​
제공되는 메트릭

​
게시물 지표

지표유형필드 경로
리포스트공개public_metrics.retweet_count
인용공개public_metrics.quote_count
좋아요공개public_metrics.like_count
답글공개public_metrics.reply_count
노출 수비공개non_public_metrics.impression_count
URL 클릭 수비공개non_public_metrics.url_link_clicks
프로필 클릭 수비공개non_public_metrics.user_profile_clicks

​
미디어 지표(동영상)

지표유형필드 경로
조회 수공개public_metrics.view_count
재생 0%비공개non_public_metrics.playback_0_count
재생 25%비공개non_public_metrics.playback_25_count
재생 50%비공개non_public_metrics.playback_50_count
재생 75%비공개non_public_metrics.playback_75_count
재생 100%비공개non_public_metrics.playback_100_count

​
메트릭 요청하기

​
공개 지표(모든 인증)

curl "https://api.x.com/2/tweets/1234567890?tweet.fields=public_metrics" \
  -H "Authorization: Bearer $TOKEN"
응답: 
{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "public_metrics": {
      "retweet_count": 50,
      "reply_count": 12,
      "like_count": 234,
      "quote_count": 5
    }
  }
}

​
비공개 메트릭 (사용자 컨텍스트)

사용자가 소유한 게시물의 경우 사용자 컨텍스트를 사용하는 OAuth 1.0a 또는 OAuth 2.0 인증이 필요합니다: 
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=non_public_metrics,organic_metrics" \
  -H "Authorization: OAuth oauth_consumer_key=...,oauth_token=..."
응답: 
{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "non_public_metrics": {
      "impression_count": 5432,
      "url_link_clicks": 89,
      "user_profile_clicks": 156
    },
    "organic_metrics": {
      "impression_count": 5432,
      "like_count": 234,
      "reply_count": 12,
      "retweet_count": 50,
      "url_link_clicks": 89,
      "user_profile_clicks": 156
    }
  }
}

​
동영상 메트릭

동영상 재생 메트릭을 위해서는 media expansion을 사용하세요: 
curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=attachments&\
expansions=attachments.media_keys&\
media.fields=public_metrics,non_public_metrics" \
  -H "Authorization: OAuth ..."
응답: 
{
  "data": {
    "id": "1234567890",
    "text": "Check out this video!",
    "attachments": {
      "media_keys": ["13_9876543210"]
    }
  },
  "includes": {
    "media": [{
      "media_key": "13_9876543210",
      "type": "video",
      "public_metrics": {
        "view_count": 12543
      },
      "non_public_metrics": {
        "playback_0_count": 12543,
        "playback_25_count": 9876,
        "playback_50_count": 7654,
        "playback_75_count": 5432,
        "playback_100_count": 3210
      }
    }]
  }
}

​
자연 vs. 프로모션 지표

게시물이 광고로 프로모션된 경우, 지표는 자연 노출과 프로모션 노출로 나뉩니다:
ContextDescription
Organic일반 타임라인 노출에서 발생한 지표
Promoted유료 광고 노출에서 발생한 지표
Public합산 전체(자연 + 프로모션) 지표
세부 구성을 확인하려면 두 가지 모두를 요청하세요: 
tweet.fields=public_metrics,organic_metrics,promoted_metrics

​
지표 정의

게시물이 사용자의 화면에 표시된 횟수입니다. 고유 사용자 기준이 아니며, 동일 사용자가 두 번 조회하면 두 번의 노출로 집계됩니다.
리포스트(리트윗) 횟수입니다. 인용 게시물은 포함되지 않습니다.
인용 게시물(댓글을 덧붙여 리포스트한 게시물) 수입니다. 항상 유기 트래픽으로 집계됩니다.
해당 동영상을 포함하는 모든 게시물을 기준으로 집계한 값입니다. 동일한 동영상이 여러 게시물에서 리포스트되더라도, 동영상 하나에 대해 전체 조회수는 하나의 합산된 수치로 제공됩니다.
동영상의 각 구간(퍼센트 지점)까지 재생한 고유 사용자 수입니다. 이탈률을 파악하는 데 유용합니다.

​
요구 사항 요약

Metric field필요한 인증
public_metricsBearer 토큰 (제한 없음)
non_public_metrics사용자 컨텍스트 (소유한 포스트에 한함)
organic_metrics사용자 컨텍스트 (소유한 포스트에 한함)
promoted_metrics사용자 컨텍스트 (프로모션된 포스트에 한함)

​
다음 단계

데이터 사전

전체 필드 레퍼런스입니다.

인증

사용자 컨텍스트 인증을 설정하세요.