oEmbed API

The oEmbed API returns simple embed HTML in an oEmbed-compatible format. You can use the oEmbed API to programmatically return embedded content, such as Tweets and timelines

The response from the oEmbed API will return an HTML snippet that will be automatically recognized when Twitter's widget JavaScript is included on the page.

Please note that the API is recommended for performing tasks in bulk, and we advise using our robust publish.twitter.com tool for embedding content.

The returned HTML snippet will be automatically recognized as an embedded timeline when Twitter's widget JavaScript is included on the page.

The oEmbed endpoint allows customization of the final appearance of an embedded timeline by setting the corresponding properties in HTML markup to be interpreted by Twitter's JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as Twitter adds new features or adjusts its timeline representation.

For a Twitter timeline specified by the timeline URL, in an oEmbed-compatible JSON format. User and list timelines are supported. The timeline markup is meant to be cached on your servers for up to the suggested cache lifetime specified by the cache_age property.

Resource URL

https://publish.twitter.com/oembed

Resource Information

Response formats JSON
Requires authentication? No
Rate limited No

Parameters

Name Description Example
url The URL of the Twitter timeline to be embedded

    Profile: https://twitter.com/TwitterDev

    List: https://twitter.com/TwitterDev/lists/national-parks

widget_type Collection timelines only. Set to grid to display Tweets in a grid layout grid
limit Display up to N items where N is a value between 1 and 20 inclusive 6
maxwidth Set the maximum width of the widget. Must be between 180 and 1200 inclusive 300
maxheight Set the maximum height of the widget. Must be greater than 200 400
omit_script Do not include a script element in the response 1
lang A supported Twitter language code es
related Suggest additional Twitter screen names related to the widget as comma-separated values. Twitter may suggest these accounts to follow after the user likes a displayed Tweet. You may provide a brief description of how the account relates to the Tweet with a URL-encoded comma and text after the screen name twitter%3ATwitter%20News,twitterapi%3ATwitter%20API%20News
theme When set to dark, the timeline is displayed with light text over a dark background dark
border_color Set the color of widget component borders, including the border between Tweets, with a hexadecimal color value %23a80000
chrome

Remove a timeline display component with space-separated tokens

    noheader - hides the header

    nofooter - hides the footer, if visible

    noborders - removes all borders: around the widget, between Tweets, and inside a Tweet

    noscrollbar - crop and hide the timeline scrollbar, if visible

    transparent - remove background color

noheader%20nofooter
aria_polite Set an assertive ARIA live region politeness value for Tweets added to a timeline assertive
dnt When set to true, the timeline and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads true

 

Example requests

      curl --request GET --url 'https://publish.twitter.com/oembed?url=https%3A%2F%2Ftwitter.com%2Ftwiterdev'
    
      twurl -H publish.twitter.com "/oembed?url=https://twitter.com/TwitterDev"
    

Example response

      {
  "url": "https://twitter.com/Twiterdev",
  "title": "",
  "html": "<a class=\"twitter-timeline\" href=\"https://twitter.com/Twiterdev?ref_src=twsrc%5Etfw\">Tweets by Twiterdev</a>\n<script async src=\"https://platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>\n",
  "width": null,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https://twitter.com",
  "version": "1.0"
}
    

The returned HTML snippet will be automatically recognized as an embedded Tweet when Twitter's widget JavaScript is included on the page

The oEmbed endpoint allows customization of the final appearance of an Embedded Tweet by setting the corresponding properties in HTML markup to be interpreted by Twitter's JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as Twitter adds new features or adjusts its Tweet representation.

The Tweet fallback markup is meant to be cached on your servers for up to the suggested cache lifetime specified by the cache_age property.

Resource URL

https://publish.twitter.com/oembed

Resource Information

Response formats JSON
Requires authentication? No
Rate limited No

Parameters

Name Default Description
urlrequired
String
  The URL of the Tweet to be embedded
maxwidth
Int [220..550]
325 The maximum width of a rendered Tweet in whole pixels. A supplied value under or over the allowed range will be returned as the minimum or maximum supported width respectively; the reset width value will be reflected in the returned width property. Note that Twitter does not support the oEmbed maxheight parameter. Tweets are fundamentally text, and are therefore of unpredictable height that cannot be scaled like an image or video. Relatedly, the oEmbed response will not provide a value for height. Implementations that need consistent heights for Tweets should refer to the hide_thread and hide_media parameters below.
hide_media
Boolean, String or Int
false When set to true, "t", or 1 links in a Tweet are not expanded to photo, video, or link previews.
hide_thread
Boolean, String or Int
false When set to true, "t", or 1 a collapsed version of the previous Tweet in a conversation thread will not be displayed when the requested Tweet is in reply to another Tweet.
omit_script
Boolean, String or Int
false When set to true, "t", or 1 the <script> responsible for loading widgets.js will not be returned. Your webpages should include their own reference to widgets.js for use across all Twitter widgets including Embedded Tweets.
align
Enum {left,right,center,none}
none Specifies whether the embedded Tweet should be floated left, right, or center in the page relative to the parent element.
related
String
  A comma-separated list of Twitter usernames related to your content. This value will be forwarded to Tweet action intents if a viewer chooses to reply, like, or retweet the embedded Tweet.
lang
Enum(Language)
en Request returned HTML and a rendered Tweet in the specified Twitter language supported by embedded Tweets.
theme
Enum {light, dark}
light When set to dark, the Tweet is displayed with light text over a dark background.
link_color
String
  Adjust the color of Tweet text links with a hexadecimal color value.
widget_type
Enum {video}
  Set to video to return a Twitter Video embed for the given Tweet.
dnt
Boolean
false When set to true, the Tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.

Example requests

      curl --request GET --url 'https://publish.twitter.com/oembed?url=https%3A%2F%2Ftwitter.com%2FInterior%2Fstatus%2F507185938620219395'
    
      twurl -H publish.twitter.com "/oembed?url=https://twitter.com/Interior/status/463440424141459456"
    

Example response

      {
  "url": "https://twitter.com/Interior/status/507185938620219395",
  "author_name": "US Department of the Interior",
  "author_url": "https://twitter.com/Interior",
  "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">Happy 50th anniversary to the Wilderness Act! Here&#39;s a great wilderness photo from <a href=\"https://twitter.com/YosemiteNPS?ref_src=twsrc%5Etfw\">@YosemiteNPS</a>. <a href=\"https://twitter.com/hashtag/Wilderness50?src=hash&amp;ref_src=twsrc%5Etfw\">#Wilderness50</a> <a href=\"http://t.co/HMhbyTg18X\">pic.twitter.com/HMhbyTg18X</a></p>&mdash; US Department of the Interior (@Interior) <a href=\"https://twitter.com/Interior/status/507185938620219395?ref_src=twsrc%5Etfw\">September 3, 2014</a></blockquote>\n<script async src=\"https://platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>\n",
  "width": 550,
  "height": null,
  "type": "rich",
  "cache_age": "3153600000",
  "provider_name": "Twitter",
  "provider_url": "https://twitter.com",
  "version": "1.0"
}
    
Was this document helpful?
Thank you

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.