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

 
alt_text string

A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment. 

"alt_text": “Rugged hills along the Na Pali coast on the island of Kauai”

Can be used to provide a written description of an image in case a user is visually impaired.

 

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,alt_text' --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
            }
        ]
    }
}