Media

Media refers to any image, GIF, or video attached to a Tweet. The media object is not a primary object on any endpoint, but can be found and expanded in the Tweet object. 

The object is available for expansion with ?expansions=attachments.media_keys to get the condensed object with only default fields. Use the expansion with the field parameter: media.fields when requesting additional fields to complete the object.

 

Field value Type Description How it can be used

media_key (default)

string

Unique identifier of the expanded media content.

"media_key": "13_1263145212760805376"

Can be used to programmatically retrieve media

type (default)

string

Type of content (animated_gif, photo, video).

"type": "video"

Classify the media as a photo, GIF, or video

duration_ms

integer

Available when type is video. Duration in milliseconds of the video.

"duration_ms": 46947

 

height

integer

Height of this content in pixels.

"height": 1080

 

non_public_metrics

object

Non-public engagement metrics for the media content at the time of the request. 

Requires user context authentication.

"non_public_metrics": {
         "playback_0_count": 1561,
         "playback_100_count": 116,
         "playback_25_count": 559,
         "playback_50_count": 305,
         "playback_75_count": 183,
       }

Determine video engagement: how many users played through to each quarter of the video.

organic_metrics

object


Engagement metrics for the media content, tracked in an organic context, at the time of the request. 

Requires user context authentication.

"organic_metrics": {
         "playback_0_count": 1561,
         "playback_100_count": 116,
         "playback_25_count": 559,
         "playback_50_count": 305,
         "playback_75_count": 183,
         "view_count": 629
       }

Determine organic media engagement.

preview_image_url

string

URL to the static placeholder preview of this content.

"preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg"


 

promoted_metrics

object

Engagement metrics for the media content, tracked in a promoted context, at the time of the request. 

Requires user context authentication.

"promoted_metrics": {
         "playback_0_count": 259,
         "playback_100_count": 15,
         "playback_25_count": 113,
         "playback_50_count": 57,
         "playback_75_count": 25,
         "view_count": 124
       }

Determine media engagement when the Tweet was promoted.

public_metrics

object

Public engagement metrics for the media content at the time of the request.

"public_metrics": {
         "view_count": 6865141
       }

Determine total number of views for the video attached to the Tweet.

width

integer

Width of this content in pixels.

"width": 1920

 

 

Retrieving a media object

Sample Request

In the following request, we are requesting fields for the media object attached to the Tweet on the Tweet lookup endpoint. Since media is a child object of a Tweet, the attachment.media_keys expansion is required. Be sure to replace $BEARER_TOKEN with your own generated bearer token.
 

  curl --request GET 'https://api.twitter.com/2/tweets?ids=1263145271946551300&expansions=attachments.media_keys&media.fields=duration_ms,height,media_key,preview_image_url,public_metrics,type,url,width' --header 'Authorization: Bearer $BEARER_TOKEN'


Sample Response
 

{
    "data": [
        {
            "text": "Testing, testing...\n\nA new way to have a convo with exactly who you want. We’re starting with a small % globally, so keep your 👀 out to see it in action. https://t.co/pV53mvjAVT",
            "id": "1263145271946551300",
            "attachments": {
                "media_keys": [
                    "13_1263145212760805376"
                ]
            }
        }
    ],
    "includes": {
        "media": [
            {
                "duration_ms": 46947,
                "type": "video",
                "height": 1080,
                "media_key": "13_1263145212760805376",
                "public_metrics": {
                    "view_count": 6909260
                },
                "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg",
                "width": 1920
            }
        ]
    }
}

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.