oEmbed API

Return a simple embed HTML for a Twitter timeline specified by the timeline URL, in an oEmbed-compatible JSON format. User, list, likes, and collection 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
  • https://twitter.com/TwitterDev
  • 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

      GET https://publish.twitter.com/oembed?url=https://twitter.com/TwitterDev
twurl -H publish.twitter.com "/oembed?url=https://twitter.com/TwitterDev"

Example Response

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