Skip to main content
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 X’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.x.com tool for embedding content.
  • Embedded timelines
  • Embedded Tweets
The returned HTML snippet will be automatically recognized as an embedded timeline when X’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 X’s JavaScript bundled with the HTML response by default. The format of the returned markup may change over time as X adds new features or adjusts its timeline representation.For a X 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.x.com/oembed

​
Resource Information

Response formatsJSON
Requires authentication?No
Rate limitedNo

​
Parameters

NameDescriptionExample
urlThe URL of the X timeline to be embedded* https://x.com/TwitterDev
*https://x.com/TwitterDev/lists/national-parks
limitDisplay up to N items where N is a value between 1 and 20 inclusive6
maxwidthSet the maximum width of the widget. Must be between 180 and 1200 inclusive300
maxheightSet the maximum height of the widget. Must be greater than 200400
omit_scriptDo not include a script element in the response1
langA supported X language codees
themeWhen set to dark, the timeline is displayed with light text over a dark backgrounddark
chromeRemove 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_politeSet an assertive ARIA live region politeness value for Tweets added to a timelineassertive
dntWhen set to true, the timeline and its embedded page on your site are not used for purposes that include personalized suggestions and personalized adstrue

​
Example Requests

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

​
Example Response


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