Skip to main content
The X API provides engagement metrics for posts and media. Access public metrics with any authentication, or private metrics for your own content with user authentication.

​
Metric types

TypeAuthenticationDescription
PublicBearer TokenVisible to anyone (likes, reposts, replies)
Non-publicUser contextPrivate metrics (impressions, clicks)
OrganicUser contextMetrics from non-promoted views
PromotedUser contextMetrics from ad views
30-day limit: Non-public, organic, and promoted metrics are only available for posts created within the last 30 days.

​
Available metrics

​
Post metrics

MetricTypeField path
RepostsPublicpublic_metrics.retweet_count
QuotesPublicpublic_metrics.quote_count
LikesPublicpublic_metrics.like_count
RepliesPublicpublic_metrics.reply_count
ImpressionsNon-publicnon_public_metrics.impression_count
URL clicksNon-publicnon_public_metrics.url_link_clicks
Profile clicksNon-publicnon_public_metrics.user_profile_clicks

​
Media metrics (videos)

MetricTypeField path
ViewsPublicpublic_metrics.view_count
Playback 0%Non-publicnon_public_metrics.playback_0_count
Playback 25%Non-publicnon_public_metrics.playback_25_count
Playback 50%Non-publicnon_public_metrics.playback_50_count
Playback 75%Non-publicnon_public_metrics.playback_75_count
Playback 100%Non-publicnon_public_metrics.playback_100_count

​
Requesting metrics

​
Public metrics (any auth)

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

​
Private metrics (user context)

Requires OAuth 1.0a or OAuth 2.0 with user context for posts you own: 
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=non_public_metrics,organic_metrics" \
  -H "Authorization: OAuth oauth_consumer_key=...,oauth_token=..."
Response: 
{
  "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
    }
  }
}

​
Video metrics

For video playback metrics, use the 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 ..."
Response: 
{
  "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
      }
    }]
  }
}

​
Organic vs. promoted metrics

If a post was promoted as an ad, metrics split between organic and promoted views:
ContextDescription
OrganicMetrics from normal timeline views
PromotedMetrics from paid ad impressions
PublicCombined total (organic + promoted)
Request both to see the breakdown: 
tweet.fields=public_metrics,organic_metrics,promoted_metrics

​
Metric definitions

Count of times the post appeared on a user’s screen. Not unique—the same user viewing twice counts as two impressions.
Number of reposts (retweets). Does not include quote posts.
Number of quote posts (reposts with comment). These are always organic.
Aggregated across all posts containing the video. A video reposted in multiple posts has one total view count.
Number of unique users who played through each percentage of the video. Useful for understanding drop-off rates.

​
Requirements summary

Metric fieldAuthentication required
public_metricsBearer Token (any)
non_public_metricsUser context (owned posts only)
organic_metricsUser context (owned posts only)
promoted_metricsUser context (promoted posts only)

​
Next steps

Data Dictionary

Complete field reference.

Authentication

Set up user context auth.