> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# oEmbed API

> 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.

You can use the oEmbed API to programmatically return embedded content, such as [Tweets](https://developer.x.com/en/docs/twitter-for-websites/embedded-tweets/overview) and [timelines](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview). 

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](https://developer.x.com/web/javascript/loading).

Please note that the API is recommended for performing tasks in bulk, and we advise using our robust [publish.x.com](https://publish.x.com/#) tool for embedding content.

<Tabs>
  <Tab title="Embedded timelines">
    The returned HTML snippet will be automatically recognized as an [embedded timeline](https://developer.x.com/en/docs/twitter-for-websites/timelines/overview) when [X's widget JavaScript is included on the page](https://developer.x.com/web/javascript/loading).

    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](https://oembed.com/)-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](https://publish.x.com/oembed)*

    ## Resource Information

    |                          |      |
    | :----------------------- | :--- |
    | 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/TwitterDev](https://x.com/TwitterDev)<br /> \*[https://x.com/TwitterDev/lists/national-parks](https://x.com/TwitterDev/lists/national-parks) |
    | 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](/x-for-websites/supported-languages "X language code")                                                                                                                                                                                                                                                                                                  | es                                                                                                                                                               |
    | theme        | When set to dark, the timeline is displayed with light text over a dark background                                                                                                                                                                                                                                                                                                    | dark                                                                                                                                                             |
    | chrome       | Remove a timeline display component with space-separated tokens<br /><br />\*   noheader - hides the header<br />\*   nofooter - hides the footer, if visible<br />\*   noborders - removes all borders: around the widget, between Tweets, and inside a Tweet<br />\*   noscrollbar- crop and hide the timeline scrollbar, if visible<br />\*   transparent- remove background color | noheader%20nofooter                                                                                                                                              |
    | aria\_polite | Set an assertive [ARIA live region politeness](https://www.w3.org/TR/wai-aria/states_and_properties#aria-live) 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](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405)                                                                                                                                          | true                                                                                                                                                             |

    ## Example Requests

    ```bash theme={null}
    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

    ```json theme={null}

    {
      "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"
    }
    ```
  </Tab>

  <Tab title="Embedded Tweets">
    The returned HTML snippet will be automatically recognized as an [embedded Tweet](https://developer.x.com/web/embedded-tweets) when [X's widget JavaScript is included on the page](https://developer.x.com/web/javascript/loading). 

    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 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 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.x.com/oembed](https://publish.x.com/oembed)*

    ## Resource Information

    |                          |      |
    | :----------------------- | :--- |
    | Response formats         | JSON |
    | Requires authentication? | No   |
    | Rate limited             | No   |

    ## Parameters

    | Name                                                                                                                                   | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
    | :------------------------------------------------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `url`required  <br />String                                                                                                            |         | The URL of the Tweet to be embedded                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
    | `maxwidth`  <br />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 X 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`  <br />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`  <br />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`  <br />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 X widgets including [Embedded Tweets](https://developer.x.com/web/embedded-tweets).                                                                                                                                                                                                                                                                                                                                                                 |
    | `align`  <br />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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
    | `lang`  <br />Enum([Language](https://developer.x.com/en/docs/twitter-for-websites/twitter-for-websites-supported-languages/overview)) | `en`    | Request returned HTML and a rendered Tweet in the specified [X language supported by embedded Tweets](https://developer.x.com/web/overview/languages).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
    | `theme`  <br />Enum `{light, dark}`                                                                                                    | `light` | When set to `dark`, the Tweet is displayed with light text over a dark background.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
    | `dnt`  <br />Boolean                                                                                                                   | `false` | When set to `true`, the Tweet and its embedded page on your site are not used for purposes that include [personalized suggestions](https://support.x.com/articles/20169421) and [personalized ads](https://support.x.com/articles/20170405).                                                                                                                                                                                                                                                                                                                                                                                                        |

    ## Example Requests

    ```bash theme={null}
    curl --request GET --url 'https://publish.x.com/oembed?url=https%3A%2F%2Ftwitter.com%2Ftwiterdev'
    twurl -H publish.x.com "/oembed?url=https://x.com/TwitterDev"
    ```

    ## Example Response

    ```json theme={null}
    {
      "url": "https:\/\/twitter.com\/Interior\/status\/463440424141459456",
      "author_name": "US Department of the Interior",
      "author_url": "https:\/\/twitter.com\/Interior",
      "html": "<blockquote class=\"twitter-tweet\"><p lang=\"en\" dir=\"ltr\">Sunsets don&#39;t get much better than this one over <a href=\"https:\/\/twitter.com\/GrandTetonNPS?ref_src=twsrc%5Etfw\">@GrandTetonNPS<\/a>. <a href=\"https:\/\/twitter.com\/hashtag\/nature?src=hash&amp;ref_src=twsrc%5Etfw\">#nature<\/a> <a href=\"https:\/\/twitter.com\/hashtag\/sunset?src=hash&amp;ref_src=twsrc%5Etfw\">#sunset<\/a> <a href=\"http:\/\/t.co\/YuKy2rcjyU\">pic.x.com\/YuKy2rcjyU<\/a><\/p>&mdash; US Department of the Interior (@Interior) <a href=\"https:\/\/twitter.com\/Interior\/status\/463440424141459456?ref_src=twsrc%5Etfw\">May 5, 2014<\/a><\/blockquote>\n<script async src=\"https:\/\/platform.x.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"
    }
    ```
  </Tab>
</Tabs>