oEmbed API

Return a simple embed HTML for a X timeline specified by the timeline URL, in an oEmbed-compatible JSON format. User, list, likes, and collection timelines.

Return a simple embed HTML for a X 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.x.com/oembed

Resource Information

Feature	Value
Response formats	JSON
Requires authentication?	No
Rate limited	No

Parameters

Name	Description	Example
url	The URL of the X timeline to be embedded	https://x.com/XDevelopers https://x.com/XDevelopers/lists/national-parks
widget_type	Collection timelines only. Set to grid to display Posts 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 X language code	es
related	Suggest additional X screen names related to the widget as comma-separated values. X may suggest these accounts to follow after the user likes a displayed Post. You may provide a brief description of how the account relates to the Post with a URL-encoded comma and text after the screen name	x%3AX%20News,xapi%3AX%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 Posts, 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 Posts, and inside a Post • 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 Posts 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.x.com/oembed?url=https://x.com/XDevelopers
twurl -H publish.x.com "/oembed?url=https://x.com/XDevelopers"

Example Response

{
  "url": "https://x.com/XDevelopers",
  "title": "",
  "html": "<a class=\"twitter-timeline\" href=\"https://x.com/XDevelopers\">Posts by XDevelopers</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": "X",
  "provider_url": "https://x.com",
  "version": "1.0"
}