diff --git a/x-ads-api/creatives.mdx b/x-ads-api/creatives.mdx index c737fd07b..815fe9d73 100644 --- a/x-ads-api/creatives.mdx +++ b/x-ads-api/creatives.mdx @@ -1,19 +1,10 @@ --- -title: Creatives -sidebarTitle: Overview -description: Create and manage promotable creatives on X including Tweets, images, videos, GIFs, cards, polls, and conversation cards. Upload media and associate creatives with campaigns and line items. -keywords: ["creatives", "ad creatives", "cards", "promoted tweets", "video creatives", "creative management", "ads api creatives"] +title: "Creatives" +keywords: ["creatives", "ad creatives", "creative management", "ad creative API", "manage creatives", "advertising creatives"] --- import { Button } from "/snippets/button.mdx"; -**Manage all types of promotable content (Tweets, media, cards, polls, etc.) for your X advertising campaigns.** - -## Quick Links - -- [Full API Reference](/x-ads-api/creatives/reference) — Complete reference for all creative endpoints and objects -- [Guides](#guides) — Media Library, Scheduled Tweets, Identifying Cards/Media, Carousels, etc. - ## Overview Creatives are any entity that can be promoted in a campaign. Posts can include text, images, GIFs, videos, or cards. Cards can include images or videos. @@ -21,11 +12,10 @@ Creatives are any entity that can be promoted in a campaign. Posts can include t Image, GIF, or video creatives are uploaded using either the [POST media/upload](/x-api/media/upload-media#post-media-upload) — a simple upload endpoint that only supports images — or the POST media/upload (chunked) endpoints. These can be added to cards: -- POST accounts/:account_id/cards -Tweets: -- POST accounts/:account_id/tweets - To add cards to Tweets, use the card_uri parameter. -Scheduled Tweets: -- POST accounts/:account_id/scheduled_tweets + +- POST accounts/:account\_id/cards Tweets: +- POST accounts/:account\_id/tweets - To add cards to Tweets, use the card\_uri parameter. Scheduled Tweets: +- POST accounts/:account\_id/scheduled\_tweets For additional details on cards, please see the Cards page. The Promoted Video page provides details on associating videos with cards or Tweets. @@ -35,7 +25,7 @@ The Ads API supports several card types that can be used in Tweets, which can th #### Image -The following image specifications apply to assets used in [Cards](/x-ads-api/creatives/reference#cards-2). Images must be 3MB or less and have an a width of at least 800px. In addition, we support the following width:height aspect ratios. +The following image specifications apply to assets used in [Cards](/x-ads-api/creatives#cards-2). Images must be 3MB or less and have an a width of at least 800px. In addition, we support the following width:height aspect ratios. - Website: 1:1 and 1.91:1 - Image App Download: 1:1 and 1.91:1 @@ -47,7 +37,7 @@ We support the following image formats: .bmp, .jpeg, and .png. #### Video -The following video specifications apply to assets used in [Cards](/x-ads-api/creatives/reference#cards-2). We support the following width:height aspect ratios. +The following video specifications apply to assets used in [Cards](/x-ads-api/creatives#cards-2). We support the following width:height aspect ratios. - Video Website: 16:9 and 1:1 - Video App Download: 16:9 and 1:1 @@ -59,17 +49,17 @@ The following video specifications apply to assets used in [Cards](/x-ads-api/cr This document provides a brief overview of the process for uploading and promoting video through the Ads API. -The Ads API supports Promoted Video in [Tweets](/x-ads-api/creatives/reference#tweets-2) and in the following cards: +The Ads API supports Promoted Video in [Tweets](/x-ads-api/creatives#tweets-2) and in the following cards: - [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814) - [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814) -- [Video Conversation](/x-ads-api/creatives/reference#video-conversation-cards) +- [Video Conversation](/x-ads-api/creatives#video-conversation-cards) First, upload the video using the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using the `media_id`, associate the video with an ads account using the POST accounts/:account\_id/videos endpoint. The video's `id`, sometimes referred to as the `media_key`, will be used in subsequent requests. This is a string that begins with an int, is followed by an underscore, and ends with a long value. As an example, see: `13_875943225764098048`. #### Promoted Video in Tweets -To create a Tweet, use the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#get-accounts-account-id-tweets) endpoint along with the video's `id`. In this step, you can also provide a video title, description, and call-to-action (CTA). These values are user-facing. +To create a Tweet, use the [POST accounts/:account\_id/tweet](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint along with the video's `id`. In this step, you can also provide a video title, description, and call-to-action (CTA). These values are user-facing. #### Promoted Video in Cards @@ -89,7 +79,7 @@ Finally, create the Tweet using the POST accounts/:account\_id/tweet endpoint. C For detailed guidance on video uploading through the API, please see the [Video Upload Guide](/x-api/media/quickstart/media-upload-chunked). -Videos can also be promoted as pre-roll assets. See the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management/reference#video-views-preroll-objective) for a detailed explanation. +Videos can also be promoted as pre-roll assets. See the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) for a detailed explanation. - (As of 2015-10-22) When uploading videos to be used in promoted content, the `media_category` parameter must be set with a value of `amplify_video` for all `INIT` command requests to the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using this new param ensures that the video is asynchronously pre-processed and prepared for use in promoted content. The `STATUS` command can be used to check completion of asynchronous processing after video upload. - The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less. @@ -118,23 +108,23 @@ The entire set of endpoints related to the above functionality is listed below: #### Scheduled Tweet Management -- [GET accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#get-accounts-account-id-scheduled-tweets) (retrieve a list of all Scheduled Tweets) -- [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#get-accounts-account-id-scheduled-tweets) (lookup a specific Scheduled Tweet using its `id`) -- [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets) (create a new Scheduled Tweet) -- [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#example-request-39) (modify an existing Scheduled Tweet) -- [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#example-request-40) (delete a Scheduled Tweet using its `id`) -- [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#scheduled-tweets-2) (preview an existing Scheduled Tweet) +- [GET accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (retrieve a list of all Scheduled Tweets) +- [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (lookup a specific Scheduled Tweet using its `id`) +- [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets) (create a new Scheduled Tweet) +- [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#example-request-39) (modify an existing Scheduled Tweet) +- [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#example-request-40) (delete a Scheduled Tweet using its `id`) +- [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweets-2) (preview an existing Scheduled Tweet) #### Scheduled Promoted Tweets -- [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management/reference#get-accounts-account-id-scheduled-promoted-tweets) (retreive a list of all Scheduled Promoted Tweets) -- [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management/reference#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (lookup a Promoted Scheduled Tweet using its `id`) -- [POST accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management/reference#post-accounts-account-id-scheduled-promoted-tweets) (create a new Scheduled Promoted Tweet) -- [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management/reference#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (delete an existing Scheduled Promoted Tweet using its `id`) +- [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (retreive a list of all Scheduled Promoted Tweets) +- [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (lookup a Promoted Scheduled Tweet using its `id`) +- [POST accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (create a new Scheduled Promoted Tweet) +- [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (delete an existing Scheduled Promoted Tweet using its `id`) #### Scheduled Tweet View -- [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives/reference#scheduled-tweets-2) (view an existing Scheduled Tweet) +- [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweets-2) (view an existing Scheduled Tweet) Due to the nature of Scheduled Tweets being separate entities from “live” Tweets, there are two different sets of validations run on any creates or edits to these Tweets. The first set of validation rules are run during the Scheduled Tweet creation step, specifically: @@ -155,8 +145,8 @@ A new Scheduled Tweet can be created using the [POST accounts/:account\_id/sched Once a Scheduled Tweet is successfully created, the response will contain an `id` field, which refers to the unique identifier of the Scheduled Tweet itself. In addition to this field, another field called `tweet_id` is also returned. This field is `null` initially, however once the Tweet goes live this field is populated with the ID of the “live” Tweet. -``` -twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!' +```text +twurl -H 'ads-api.x.com' -X POST "/12/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!' ``` This will create the following Scheduled Tweet: @@ -171,7 +161,6 @@ This will create the following Scheduled Tweet: }, "data": { "completed_at": null, - "id_str": "917507899668099072", "text": "Happy Holidays!", "user_id": "3271358660", "scheduled_status": "SCHEDULED", @@ -193,8 +182,8 @@ Once this Scheduled Tweet goes live, the `tweet_id` field will be populated with The [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) endpoint can then be used with the Scheduled Tweet `id` from the previous step to generate a preview of the Tweet. The API response will contain an iframe URL that is ready to be used to render a preview for the Scheduled Tweet. The relevant CSS and images will be served directly via X. -``` -twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072 +```text +twurl -H ads-api.x.com -X GET "/12/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072 ``` ```json @@ -225,8 +214,8 @@ While Scheduled Tweets can be used to create Organic Tweets, we also allow partn Please note that it is not possible to modify an existing Scheduled Promoted Tweet. -``` -twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072' +```text +twurl -H 'ads-api.x.com' -X POST "/12/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072' ``` ```json @@ -288,13 +277,13 @@ The Media Library endpoints provide the ability to manage images, GIFs, and vide #### API Endpoints - [POST media/upload](/x-api/media/upload-media) or [POST media/upload (chunked)](/x-api/media/initialize-media-upload) (upload media) -- [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives/reference#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (add media to the Media Library) +- [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (add media to the Media Library) #### Adding to the Library Adding media to the library is a two-step process. First, upload the asset using either the [POST media/upload](/x-api/media/upload-media) endpoint or the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) set of endpoints. (See the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) guide for details on our multi-part upload process.) -``` +```text twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media" ``` @@ -312,10 +301,10 @@ twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=75620119 } ``` -Next, using the media ID, add the media to the ads account’s library using the [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives/reference#get-accounts-account-id-media-library#post-accounts-account-id-media-library) endpoint. +Next, using the media ID, add the media to the ads account’s library using the [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) endpoint. -``` -twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte" +```text +twurl -X POST -H ads-api.x.com "/12/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte" ``` ```json @@ -334,11 +323,9 @@ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name= "name":"Latte", "file_name":"latte.jpeg", "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg", - "media_category":"TWEET_IMAGE", "media_key":"3_966947208837742592", "created_at":"2018-02-23T08:05:54Z", "media_status":"TRANSCODE_COMPLETED", - "media_key":"966947208837742592", "media_type":"IMAGE", "updated_at":"2018-02-23T08:06:17Z", "deleted":false @@ -360,18 +347,14 @@ For videos, it’s also possible to set a title and a description. They values a The Media Library, formally introduces the concept of the media\_key. This is the unique identifier for objects in the library. Media keys are string values in the following format: 13\_875943225764098048. These are fully supported in all of our card endpoints. -In addition, the Media Library response includes the media\_id, represented as a string. This is included for resources that do not currently accept a media key: [Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)\*, [Tweet preview](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)\*, and [Scheduled Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). We are working toward supporting media keys everywhere. - The aspect\_ratio attribute is returned for GIFs and videos. This can be used to filter media for use in cards that only accept particular aspect ratios. -\*These endpoints support the video\_id parameter, which is a media key. - #### Usage In this section, the following image will be used in a Tweet and to create a website card. -``` -twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592" +```text +twurl -H ads-api.x.com "/12/accounts/18ce54d4x5t/media_library/3_966947208837742592" ``` ```json @@ -403,8 +386,8 @@ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_9669472088377425 We can create the Tweet by referencing the images using media\_keys. -``` -twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true" +```text +twurl -X POST -H ads-api.x.com "/12/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true" ``` ```json @@ -511,8 +494,8 @@ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_ All of our cards endpoints support media keys. We will create the [website card](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/website#post-accounts-account-id-cards-website) by referencing the image’s media\_key. -``` -twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards" +```text +twurl -X POST -H ads-api.x.com "/12/accounts/18ce54d4x5t/cards" ``` ```json @@ -550,12 +533,8 @@ Cards are customizable ad formats that use media and that can be associated with Cards may be referenced in Tweet objects in one of two ways: by the card's card\_uri or by its preview\_url. Example values for each are presented below. | card\_uri | preview\_url | -| :--- | :--- | -| card://1043282691834048513 | https://cards.x.com/cards/18ce54d4x5t/68w3s | - -**Note**: As of Ads API version 3, only the card\_uri is generated and returned in the cards response for newly created cards. - -**Note**: As of Ads API version 5, the preview\_url in the cards response is no longer returned. +| :-- | :-- | +| card://1043282691834048513 | [https://cards.x.com/cards/18ce54d4x5t/68w3s](https://cards.x.com/cards/18ce54d4x5t/68w3s) | The type of reference in the Tweet object response will depend on the way the Tweet was created. In other words, if the Tweet was created using the card\_uri request parameter, the card URI value will appear in the response. If the preview\_url was included as part of the Tweet text, on the other hand, the preview URL will appear in the response. @@ -563,8 +542,8 @@ The type of reference in the Tweet object response will depend on the way the Tw For Tweets created using the card's URI value, find the reference to the card in the card\_uri response attribute. The example response below uses the [GET accounts/:account\_id/tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweets) endpoint. -``` -$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168" +```text +$ twurl -H ads-api.x.com "/12/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168" { "request": { "params": { @@ -654,7 +633,7 @@ Media—images, GIFs, and videos—can be added to Tweets and cards. In addition There are two types of media identifiers: IDs and keys. Example values for each are presented below. | **Media ID** | **Media key** | -| :--- | :--- | +| :-- | :-- | | 1029825579531807971 | 13\_1029825579531807971 | The media key is the ID plus a numeric prefix and an underscore. @@ -664,9 +643,9 @@ The media key is the ID plus a numeric prefix and an underscore. The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s). | **Resource** | **Identifier** | **Attribute(s)** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | Image cards | None | | -| Tweet | Both | `entities["media"]["id_str"]` `entities["media"]["media_key"]` | +| Tweet | Both | `entities["media"]["id_str"]entities["media"]["media_key"]` | | Scheduled Tweet | Both | `media_ids` and `media_keys` | | Draft Tweet | Both | `media_ids` and `media_keys` | | Account Media | None | | @@ -679,7 +658,7 @@ For Tweets, the id and id\_str fields in the object within the entities\["media" In addition to references to identifiers, it's often important to have access to the image's URL. | **Resource** | **Attribute(s)** | **Format** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | Image cards | `image` | .jpg | | Tweet\* | `entities["media"][0]["media_url"]` or `extended_entities["media"][i]["media_url"]` | .jpg | | Scheduled Tweet | None | | @@ -698,13 +677,13 @@ For Tweets, the media URL location depends on both the type of media and the end The following table shows the identifier types currently available in each video-related resource's response as well as the corresponding attribute name(s). | **Resource** | **Identifier** | **Attribute(s)** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | Video cards | May be either | `video_content_id` | | Video poll cards | None | | -| Tweet | Both | `entities["media"]["id_str"]` `entities["media"]["media_key"]` | +| Tweet | Both | `entities["media"]["id_str"]entities["media"]["media_key"]` | | Scheduled Tweet | Both | `media_ids` and `media_keys` | | Draft Tweet | Both | `media_ids` and `media_keys` | -| Account Media | Media key | `video_id` | +| Account Media | Media key | `media_key` | | Media Library | Both | `media_id` and `media_key` | While video cards (with the exception of poll cards with video) include a video\_content\_id response attribute, there is inconsistency in the type of value returned. In some cases, it's a media ID; in others, it's a media key. @@ -712,7 +691,7 @@ While video cards (with the exception of poll cards with video) include a video\ Information about how to access the video's URL is shown below. | **Resource** | **Attribute(s)** | **Format** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | Video cards | `video_url` and `video_hls_url` | .vmap .m3u8 | | Tweet with video | `extended_entities["media"][i]["video_info"]["variants"][j]["url"]` | .mp4 | | Scheduled Tweet | None | | @@ -720,7 +699,6 @@ Information about how to access the video's URL is shown below. | Account Media | None | | | Media Library | `media_url` | .mp4 | - Video cards include video\_url and video\_hls\_url response attributes with .vmap and .m3u8 URLs, respectively. #### Media Library @@ -738,7 +716,7 @@ Finally, media in Tweets are always guaranteed to be in the Media Library. The following table summarizes which assets are retrievable in the Media Library, taking into account whether the resource response includes an identifier to use in the lookup. | **Resource** | **In the Media Library** | -| :--- | :--- | +| :-- | :-- | | Image cards | No | | Video cards | Yes\* | | Tweets (any media)\*\* | Yes | @@ -747,8 +725,7 @@ The following table summarizes which assets are retrievable in the Media Library | Account media images | No | | Account media videos (`PREROLL`) | Yes | -\* For cards where the `video_content_id` is a media key. When the value is a media ID, the asset still exists in the Media Library, but retrieving it involves appending a numeric prefix and underscore to it. -\*\* Tweets only return media IDs. While the asset is guaranteed to exist in the Media Library, fetching it involves appending a numeric prefix and underscore to it. +\* For cards where the `video_content_id` is a media key. When the value is a media ID, the asset still exists in the Media Library, but retrieving it involves appending a numeric prefix and underscore to it. \*\* Tweets only return media IDs. While the asset is guaranteed to exist in the Media Library, fetching it involves appending a numeric prefix and underscore to it. **Interactions with Account Media** @@ -789,8 +766,8 @@ Published, scheduled, and draft Tweet IDs are [numeric](https://developer.x.com/ When published or scheduled Tweets are promoted, a corresponding promoted Tweet entity is created. These entities have their own IDs, which are alpha-numeric and are represented as base-36-encoded values. For example, promoting the published Tweet above—that is, associating it a line item 6c62d—returns the following API response. -``` -$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104" +```text +$ twurl -X POST -H ads-api.x.com "/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104" { "request": { "params": { @@ -847,19 +824,33 @@ Carousels are created using two components. The first specifies the media assets Specifically, a carousel card is created by using the following components, in order: - One `SWIPEABLE_MEDIA`component, which accepts an array of media keys -- *One* of the following: +- _One_ of the following: - A `DETAILS` component to specify website information - A `BUTTON` component to specify app information The `SWIPEABLE_MEDIA` component must include a `media_keys` array where you can specify between 2 and 6 images or videos. The order in which the media keys are passed in determine the order in which they will be rendered. -``` +```text { "type": "SWIPEABLE_MEDIA", "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" - ] + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + } } ``` @@ -868,14 +859,14 @@ As a reminder, you can obtain media keys by making a request to the [GET account The composition of the second component object depends on whether you wish to direct a user to a website or encourage them to install an app. The table below summarizes the two options. (**Note**: all of the listed keys are required.) | | **Website** | **App** | -| :--- | :--- | :--- | +| :-- | :-- | :-- | | Specify the component type | `"type": "DETAILS"` | `"type": "BUTTON"` | | Title/Label | `"title": "X"` | `"label": { "type": "ENUM", "value": "INSTALL" }` | | Destination | `"destination": { "type": "WEBSITE", "url": "https://www.x.com" }` | `"destination": { "type": "APP", ... }` | Putting this together, an example website carousel JSON POST body is shown below. -``` +```text { "name": "website carousel", "components": [ @@ -884,7 +875,21 @@ Putting this together, an example website carousel JSON POST body is shown below "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" - ] + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + } }, { "type": "DETAILS", @@ -902,7 +907,7 @@ App destination objects within `BUTTON` components require a country code and at Putting this together, an example app carousel JSON POST body is shown below. -``` +```text { "name": "app carousel", "components": [ @@ -911,7 +916,21 @@ Putting this together, an example app carousel JSON POST body is shown below. "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" - ] + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + } }, { "type": "BUTTON", @@ -940,10 +959,11 @@ To start, either upload new media assets or use existing ones. For details on ho Once your media assets are in the Media Library, fetch them using the [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library) endpoint. Use the `media_type` request parameter to scope the results to a particular media type. +```text +$ twurl -H ads-api.x.com "/12/accounts/18ce54d4x5t/media_library?media_type=VIDEO" ``` -$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO" -``` -``` + +```text { "request": { "params": { @@ -997,10 +1017,11 @@ $ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDE Use the [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) endpoint to create your carousel. Use the media keys from the previous request. Remember, the order in which the media keys are passed in determine the order in which they are rendered. +```text +$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/12/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}' ``` -$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}' -``` -``` + +```text { "request": { "params": { @@ -1015,7 +1036,21 @@ $ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accoun "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" - ] + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + } + } }, { "type": "DETAILS", @@ -1032,7 +1067,7 @@ $ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accoun "card_uri": "card://1326432421105995776", "updated_at": "2020-11-11T07:51:47Z", "deleted": false, - "card_type": "UNIFIED" + "card_type": "IMAGE_CAROUSEL_WEBSITE" } } ``` @@ -1043,10 +1078,11 @@ Notice that like with other cards, the carousel card response includes a `card_u Use the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint to create your Tweet. Use the `card_uri` from the previous request. (Response truncated for readability.) +```text +$ twurl -H ads-api.x.com "/12/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792" ``` -$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792" -``` -``` + +```text { "data": { "created_at": "Wed Nov 11 07:58:27 +0000 2020", @@ -1130,25 +1166,31 @@ The app\_id  can be found in the [Developer Console](https://developer.x.com/en The following example adds app\_id as the contributor tag and date as the date tag for an image: -``` +```text app_id:858382169 ``` -``` + +```text date:2022-03-13 ``` -``` + +```text creative_file: eiffel_tower.jpg ``` -``` + +```text exiftool -contributor=858382169 eiffel_tower.jpg ``` -``` + +```text    1 image files updated ``` -``` + +```text exiftool -date=2022-03-13 eiffel_tower.jpg ``` -``` + +```text   1 image files updated ``` @@ -1160,24 +1202,3035 @@ Example: `exiftool -xmp:all -G1 eiffel_tower.jpg` -``` +```text [XMP]        XMP Toolkit            : Image::ExifTool 12.30 ``` -``` + +```text [XMP]        Contributor            : 858382169 ``` -``` + +```text [XMP]        Date                   : 2022:03:13 ``` #### Questions? -If you would like to confirm that your tagging and attribution is successful, please provide sample assets that have been tagged to adsapi-program@x.com for a X representative to review. +If you would like to confirm that your tagging and attribution is successful, please provide sample assets that have been tagged to [adsapi-program@x.com](mailto:adsapi-program@x.com) for a X representative to review. ---- +## API Reference + +### Account Media + + + +#### GET accounts/:account\_id/account\_media + +Retrieve details for some or all account media associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_ids _optional_ | Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `3wpx` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | +| creative\_types _optional_ | Scope the response to just the account media that match the specified creative types. More than one creative type may be specified by comma-separating enum values. Type: enum Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| sort\_by _optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | +| with\_total\_count _optional_ | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_media_ids": [ + "3wpx" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "media_key": "13_771791717175468032", + "media_url": null, + "creative_type": "PREROLL", + "id": "3wpx", + "created_at": "2016-09-02T19:27:52Z", + "updated_at": "2016-09-02T19:27:52Z", + "deleted": false + } + ] +} +``` + +Retrieve a specific account media object associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_id _required_ | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_media_id": "2pnfd", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "media_key": null, + "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "2pnfd", + "created_at": "2017-07-28T01:44:41Z", + "updated_at": "2017-07-28T01:44:41Z", + "deleted": false + } +} +``` + +Delete the specified account media object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| account\_media\_id _required_ | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd` + +#### Example Response + +```text +{ + "data": { + "media_key": null, + "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig", + "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET", + "id": "2pnfd", + "created_at": "2017-07-28T01:44:41Z", + "updated_at": "2017-08-25T17:16:26Z", + "deleted": true + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "account_media_id": "2pnfd" + } + } +} +``` + +### Cards + + + +**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-tweets#post-accounts-account-id-draft-tweets) endpoints. -## Full API Reference +Retrieve details for some or all cards associated with the current account. -For the complete technical reference (all endpoints, parameters, and examples for Cards, Tweets, Media Library, Draft Tweets, Polls, Preroll, Conversation Cards, etc.), see the **[Creatives API Reference](/x-ads-api/creatives/reference)** page. +**Note**: This only returns cards that were created using the POST accounts/:account\_id/cards endpoint. Cards created using other endpoints are not returned. +#### Resource URL +`https://ads-api.x.com/12/accounts/:account_id/cards` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_types _optional_ | Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE` | +| card\_id _optional_ | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: `1044294149527166979,1044301099031658496` | +| card\_uris _optional_ | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| include\_legacy\_cards _optional_ | Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account\_id/cards/:card\_type. See [this developer forum post](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) for additional context. Type: boolean Default: `false` Possible values: `true`, `false` | +| q _optional_ | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `dtc` | +| sort\_by _optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1` + +#### Example Response + +```text +{ + "request": { + "params": { + "count": 1, + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": "8wzvldqtc", + "data": [ + { + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + } + } + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-28T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` + +Retrieve details for a single card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | The id of the cards. Type: string Example: `1044294149527166979` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data":{ + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ], + "media_metadata": { + "13_1089771253848666112": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + }, + "13_1191948012077092867": { + "type": "VIDEO", + "url": "https://pbs.twimg.com/media/EniQVJzUYAE0jaa.png", + "width": 800, + "height": 800 + } + } + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-28T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } +} +``` + +#### POST accounts/:account\_id/cards + +Create a new card associated to the specified account. + +Card create requests only accept JSON POST bodies. The `Content-Type` must be set to `application/json`. + +See our [Carousels Guide](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/carousels) for a detailed usage example. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards` + +#### Parameters + +The JSON POST body must include a card `name` and an array of `components`. Components are represented as objects and describe the advertiser-facing attributes of the card. + +The following example shows the general structure of the payload (but includes non-working information). + +```text +{ + "name": "some name", + "components": [ + { + "type": "TYPE_ENUM", + "key": "value" + } + ] +} +``` + +Additional information on components below. + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| name _required_ | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` | +| components _sometimes required_ | Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects | +| slides _sometimes required_ | Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array | + +#### Components + +Every component must include a `type` field which determines the object's schema. The Ads API supports the following component types, grouped into media- and description-based components. + +- Media: +- `MEDIA`: single video or image +- `SWIPEABLE_MEDIA`: between 2-6 videos or images +- Description: +- `DETAILS` +- `BUTTON` + +Each component has a set of required fields (in addition to the `type` key). These are listed in the following table. + +| Component `type` | Field | Value type | +| :-- | :-- | :-- | +| `MEDIA` | `media_key` | string | +| `SWIPEABLE_MEDIA` | `media_keys` | array of strings | +| `DETAILS` | `titledestination` | string object | +| `BUTTON` | `labeldestination` | object object | + +The following is an example of a `BUTTON` component in the context of the `components` array (intentionally omitting the `name` key). (The ellipses indicate places where more information would need to be specified.) + +```text +{ + "components": [ + { + "type": "BUTTON", + "label": { + ... + }, + "destination": { + ... + } + } + ] +} +``` + +The order in which the component objects are specified defines the top-to-bottom order in which they will be rendered. Cards must be created using one media-based component and either a `DETAILS` or `BUTTON` component. Description-based components are rendered under media and have associated destinations, either URLs or mobile apps. + +**Label** + +Labels define the text shown on buttons and, therefore, only apply to the `BUTTON` component. Label objects have two required keys: `type` and `value`. The `type` must be set to `ENUM` and the `value` can be one of: `BOOK`, `CONNECT`, `INSTALL`, `OPEN`, `ORDER`, `PLAY`, or `SHOP`. + +Building on the previous example, the following shows the `label` object within the `BUTTON` component. + +```text +{ + "components": [ + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + ... + } + } + ] +} +``` + +**Destination** + +Destinations are where advertisers intend to take users. They are always required within `DETAILS` or `BUTTON` components. There are two destination types: `WEBSITE` or `APP`. + +**Note**: Website destinations can only be used with `DETAILS` components and app destinations can only be used with `BUTTON` components. + +**Website Destination** + +| Name | Description | +| :-- | :-- | +| type _required_ | The destination type, which determines its schema. Type: enum Possible values: `WEBSITE` | +| url _required_ | The URL of the website to redirect a user to. Type: string Example: `https://devcommunity.x.com/c/advertiser-api` | + +**App Destination** + +| Name | Description | +| :-- | :-- | +| type _required_ | The destination type, which determines its schema. Type: enum Possible values: `APP` | +| country\_code _required_ | The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) two-letter code for the country where the app is sold. Type: string Example: `US` | +| googleplay\_app\_id _sometimes required_ | The Google Play application package name. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `com.twitter.android` | +| ios\_app\_store\_identifier _sometimes required_ | The iOS app store identifier. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `333903271` | +| googleplay\_deep\_link _optional_ | A deep link into the Android app you're promoting. **Note**: Can only be used if an `googleplay_app_id` has been provided. Type: string | +| ios\_deep\_link _optional_ | A deep link into the iOS app you're promoting. **Note**: Can only be used if an `ios_app_store_identifier` has been provided. Type: string | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards` + +```text +{ + "name": "components create cards", + "components": [ + { + "type": "MEDIA", + "media_key": "3_1323490622599176192" + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android" + } + } + ] +} +``` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "components create cards", + "components": [ + { + "type": "MEDIA", + "media_key": "3_1323490622599176192" + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "INSTALL" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android" + } + } + ], + "created_at": "2020-11-11T05:42:25Z", + "card_uri": "card://1326399865065238531", + "id": "1321554298900107264", + "updated_at": "2020-11-11T05:42:25Z", + "deleted": false, + "card_type": "IMAGE_APP" + } +} +``` + +Update the specified associated with the current account. + +Card edit requests only accept JSON POST bodies. The `Content-Type` must be set to `application/json`. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264` + +#### Parameters + +The JSON POST body must include the parameters that will be updated. The request will **replace** each field with the parameters specified within the payload. Components are represented as objects and describe the advertiser-facing attributes of the card. + +The following example shows the general structure of the payload (but includes non-working information). + +```text +{ + "name": "some name", + "components": [ + { + "type": "TYPE_ENUM", + "key": "value" + } + ] +} +``` + +Additional information on components and slides in **POST accounts/:account\_id/cards**. + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| name _optional_ | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` | +| components _optional_ | Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects | +| slides _optional_ | Use this array of array to update Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array | + +#### Example Request + +This example updates both the name and removes one of the media\_keys from the components field from the example above. + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264` + +```text +{ + "name": "changed name", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ] +} +``` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data": [ + { + "name": "changed name", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-29T20:47:52Z", + "deleted": false, + "card_type": "IMAGE_CAROUSEL_APP" + } + ] +} +``` + +Delete the specified card belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | The id of the card to be deleted. Type: string Example: `1044294149527166979` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_id": "1321554298900107264" + } + }, + "data": { + "name": "deep link", + "components": [ + { + "type": "SWIPEABLE_MEDIA", + "media_keys": [ + "3_1073727809120419840", + "3_1075096386931052545" + ] + }, + { + "type": "BUTTON", + "label": { + "type": "ENUM", + "value": "OPEN" + }, + "destination": { + "type": "APP", + "country_code": "US", + "googleplay_app_id": "com.twitter.android", + "googleplay_deep_link": "twitter://user?screen_name=apimctestface" + } + } + ], + "created_at": "2020-10-28T20:47:52Z", + "card_uri": "card://1321554298900107264", + "id": "1321554298900107264", + "updated_at": "2020-10-29T20:47:52Z", + "deleted": true, + "card_type": "IMAGE_CAROUSEL_APP" + } +} +``` + +### Cards Fetch + + + +Retrieve multiple cards, by `card_uri`, associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/all` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_uris _required_ | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_uris": [ + "card://1044294149527166979", + "card://1044301099031658496" + ], + "account_id": "18ce54d4x5t" + } + }, + "data": [ + { + "name": "X App", + "googleplay_app_id": "com.twitter.android", + "image_display_height": "836", + "country_code": "US", + "id": "692xn", + "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg", + "created_at": "2018-09-24T18:35:01Z", + "image_display_width": "1600", + "card_uri": "card://1044294149527166979", + "updated_at": "2018-09-24T18:35:01Z", + "app_cta": "INSTALL", + "deleted": false, + "card_type": "IMAGE_APP_DOWNLOAD" + }, + { + "video_poster_height": "9", + "name": "Developer Platform", + "website_shortened_url": "https://t.co/zadeUSVD18", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap", + "content_duration_seconds": "24", + "video_owner_id": "756201191646691328", + "video_content_id": "13_991374284135137280", + "website_display_url": "docs.x.com", + "id": "6933h", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2", + "website_dest_url": "https://docs.x.com", + "created_at": "2018-09-24T19:02:38Z", + "card_uri": "card://1044301099031658496", + "title": "Developer Platform", + "website_url": "https://docs.x.com", + "updated_at": "2018-09-24T19:02:38Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_WEBSITE" + } + ] +} +``` + +Retrieve a specific card, by `card_id`, associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the card you are operating with in the request. Type: string Example: `508pf` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_id": "508pf", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "video_poster_height": "9", + "name": "video website card", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap", + "content_duration_seconds": "21", + "video_owner_id": "756201191646691328", + "video_content_id": "13_867520357225418752", + "website_display_url": "docs.x.com", + "id": "508pf", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8", + "website_dest_url": "https://docs.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website", + "created_at": "2017-11-10T09:00:35Z", + "card_uri": "card://928910245920829440", + "title": "VWC", + "website_url": "https://t.co/F81hp59pUF", + "updated_at": "2018-01-05T05:43:31Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_WEBSITE" + } +} +``` + +### Draft Tweets + + + +#### GET accounts/:account\_id/draft\_tweets + +Retrieve details for some or all Draft Tweets associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-jh1g0ryb` | +| user\_id _optional_ | Specify the user to retrieve Draft Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: string Example: `756201191646691328` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1` + +#### Example Response + +```text +{ + "request": { + "params": { + "count": 1 + } + }, + "data": [ + { + "name": null, + "text": "hello, world", + "user_id": "756201191646691328", + "id": "994791681219231744", + "nullcast": true, + "created_at": "2018-05-11T04:09:53Z", + "card_uri": null, + "updated_at": "2018-05-11T04:09:53Z", + "media_keys": [] + } + ], + "next_cursor": "c-jh1g0ryb" +} +``` + +Retrieve a specific Draft Tweet associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id _required_ | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994788364334325760` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760` + +#### Example Response + +```text +{ + "request": { + "params": { + "draft_tweet_id": "994788364334325760" + } + }, + "data": { + "name": null, + "text": "#TwitterDev", + "user_id": "756201191646691328", + "id": "994788364334325760", + "nullcast": true, + "created_at": "2018-05-11T03:56:42Z", + "card_uri": "card://958225772740714496", + "updated_at": "2018-05-11T03:56:42Z", + "media_keys": [] + } +} +``` + +#### POST accounts/:account\_id/draft\_tweets + +Create a Draft Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| as\_user\_id _required_ | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: string Example: `756201191646691328` | +| text _sometimes required_ | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `Just setting up my X.` | +| card\_uri _optional_ | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://960880280705392541` | +| media\_keys _optional_ | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` | +| nullcast _optional_ | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` | +| name _optional_ | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.` + +#### Example Response + +```text +{ + "request": { + "params": { + "text": "Just setting up my X.", + "as_user_id": "756201191646691328" + } + }, + "data": { + "name": null, + "text": "Just setting up my X.", + "user_id": "756201191646691328", + "id": "994747471329873920", + "nullcast": true, + "created_at": "2018-05-11T01:14:13Z", + "card_uri": null, + "updated_at": "2018-05-11T01:14:13Z", + "media_keys": [] + } +} +``` + +Update the specified Draft Tweet belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id _required_ | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994747471329873920` | +| card\_uri _optional_ | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://970582057284129151` | +| media\_keys _optional_ | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` | +| nullcast _optional_ | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` | +| text _optional_ | The text of your status update. Type: string Example: `just setting up my twttr` | +| name _optional_ | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr` + +#### Example Response + +```text +{ + "request": { + "params": { + "draft_tweet_id": 994747471329873920, + "text": "just setting up my twttr" + } + }, + "data": { + "name": null, + "text": "just setting up my twttr", + "user_id": "756201191646691328", + "id": "994747471329873920", + "nullcast": true, + "created_at": "2018-05-11T01:14:13Z", + "card_uri": null, + "updated_at": "2018-05-11T01:16:59Z", + "media_keys": [] + } +} +``` + +Permanently delete the specified Draft Tweet belonging to the current account. + +**Note**: We **strongly** recommend deleting drafts once a Tweet or Scheduled Tweet has been created using its metadata. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Draft Tweets. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id _required_ | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994787835663155200` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200` + +#### Example Response + +```text +{ + "request": { + "params": { + "draft_tweet_id": "994787835663155200" + } + }, + "data": { + "name": null, + "text": "hello, world", + "user_id": "756201191646691328", + "id": "994787835663155200", + "nullcast": true, + "status": "DELETED", + "created_at": "2018-05-11T03:54:36Z", + "card_uri": null, + "updated_at": "2018-05-11T04:07:31Z", + "media_keys": [] + } +} +``` + +#### POST accounts/:account\_id/draft\_tweets/preview/:draft\_tweet\_id + +Preview a Draft Tweet on a mobile device. + +A successful request sends a notification to every device the authenticated user is logged in to. Clicking on the notification opens a timeline that allows the user to see and interact with the Draft Tweet, enabling them to test auto-play, volume, fullscreen, video website card docking, and other behaviors. + +**Note**: On-device previews are only visible to the user who receives the notification. + +**Note**: Notifications only get sent to X official apps. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| draft\_tweet\_id _required_ | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `996132315829948416` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "draft_tweet_id": "996132315829948416" + } + }, + "message": "See @apimctestface's notifications in the X app to preview your Tweet." +} +``` + +### Image Conversation Cards + + + +**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), or [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) endpoints. + +#### GET accounts/:account\_id/cards/image\_conversation + +Retrieve details for some or all image conversation cards associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_ids _optional_ | Scope the response to just the desired image conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `59woh` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| q _optional_ | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` | +| sort\_by _optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | +| with\_total\_count _optional_ | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_type": "image_conversation", + "card_ids": [ + "59woh" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + } + ] +} +``` + +Retrieve a specific image conversation card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the image conversation card you are operating with in the request. Type: string Example: `59woh` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_type": "image_conversation", + "card_id": "59woh", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + } +} +``` + +#### POST accounts/:account\_id/cards/image\_conversation + +Create a new image conversation card associated with the specified account. + +See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| first\_cta _required_ | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` | +| first\_cta\_tweet _required_ | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` | +| media\_key _required_ | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` | +| name _required_ | The name for the card. Type: string Example: `image conversation card` | +| thank\_you\_text _required_ | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` | +| second\_cta _sometimes required_ | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` | +| second\_cta\_tweet _sometimes required_ | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` | +| title _sometimes required_ | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` | +| third\_cta _optional_ | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` | +| third\_cta\_tweet _sometimes required_ | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` | +| fourth\_cta _optional_ | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` | +| fourth\_cta\_tweet _sometimes required_ | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` | +| unlocked\_image\_media\_key _optional_ | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` | +| thank\_you\_url _optional_ | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon` + +#### Example Response + +```text +{ + "data": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "id": "59woh", + "first_cta_tweet": "stars", + "media_key": "3_957113581522141184", + "created_at": "2018-01-27T04:58:42Z", + "image_display_width": "1280", + "card_uri": "card://923498485702009837", + "title": "Full moon", + "updated_at": "2018-01-27T04:58:42Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "name": "image conversation card", + "first_cta": "#moon", + "image_display_height": "670", + "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg", + "thank_you_text": "thanks", + "media_key": "3_957113581522141184", + "account_id": "18ce54d4x5t", + "first_cta_tweet": "stars", + "image_display_width": "1280", + "title": "Full moon", + "card_type": "IMAGE_CONVERSATION" + } + } +} +``` + +Update the specified image conversation card belonging to the current account. + +See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qg` | +| first\_cta _optional_ | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` | +| first\_cta\_tweet _optional_ | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` | +| second\_cta _optional_ | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` | +| second\_cta\_tweet _optional_ | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` | +| third\_cta _optional_ | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` | +| third\_cta\_tweet _optional_ | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` | +| fourth\_cta _optional_ | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` | +| fourth\_cta\_tweet _optional_ | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` | +| media\_key _optional_ | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` | +| name _optional_ | The name for the card. Type: string Example: `moon card` | +| thank\_you\_text _optional_ | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` | +| thank\_you\_url _optional_ | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` | +| title _optional_ | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` | +| unlocked\_image\_media\_key _optional_ | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card` + +#### Example Response + +```text +{ + "data": { + "name": "moon card", + "id": "59woh", + "created_at": "2018-01-27T04:58:42Z", + "card_uri": "card://923498485702009837", + "updated_at": "2018-01-29T21:04:39Z", + "deleted": false, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "account_id": "18ce54d4x5t", + "card_type": "IMAGE_CONVERSATION", + "card_id": "59woh", + "name": "moon card" + } + } +} +``` + +Permanently delete the specified image conversation card belonging to the current account. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qe` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe` + +#### Example Response + +```text +{ + "data": { + "name": "image conversation card", + "id": "4i0qe", + "created_at": "2017-07-07T00:03:01Z", + "updated_at": "2017-08-23T13:26:23Z", + "deleted": true, + "card_type": "IMAGE_CONVERSATION" + }, + "request": { + "params": { + "card_id": "4i0qe", + "card_type": "image_conversation", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Media Library + + + +#### GET accounts/:account\_id/media\_library + +Retrieve details for some or all media library objects associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `20` Min, Max: `1`, `50` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-1` | +| media\_type _optional_ | Scope the response to just the desired media type. Type: enum Possible values: `GIF`, `IMAGE`, `VIDEO` | +| q _optional_ | An optional query to scope resource by `name`, `title`, `file_name`, and `description` fields. **Note**: This performs case-insensitive _term_ matching. Type: string Min, Max length: `1`, `255` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "count": 1 + } + }, + "data": [ + { + "tweeted": true, + "name": null, + "file_name": "coffee https://t.co/4tcPU9XUon", + "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg", + "media_category": "TWEET_IMAGE", + "media_key": "3_908573900237180928", + "created_at": "2017-09-15T06:11:12Z", + "media_status": "TRANSCODE_COMPLETED", + "media_type": "IMAGE", + "updated_at": "2017-11-16T06:00:01Z", + "deleted": false + } + ], + "next_cursor": "c-1" +} +``` + +Retrieve a specific media library object associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key _required_ | A reference to the media library object you are operating with in the request. Type: string Example: `13_909110614026444802` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "13_909110614026444802" + } + }, + "data": { + "tweeted": true, + "duration": 39973, + "name": null, + "file_name": "buildings https://t.co/xFdzrHM5QG", + "description": null, + "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4", + "media_category": "AMPLIFY_VIDEO", + "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg", + "poster_media_key": "3_909110614026444802", + "media_key": "13_909110614026444802", + "created_at": "2017-09-16T17:43:55Z", + "media_status": "TRANSCODE_COMPLETED", + "title": "buildings", + "media_type": "VIDEO", + "aspect_ratio": "16:9", + "updated_at": "2017-09-27T13:04:00Z", + "deleted": false + } +} +``` + +Associate a media object with the current account. For additional details, please see our [Media Library guide](https://developer.x.com/en/docs/ads/creatives/guides/media-library). + +**Note**: When adding a video with the `AMPLIFY_VIDEO` media category to the Media Library, it is automatically available as a `PREROLL` [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) asset. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key _required_ | The `media_key` for the uploaded content. A `media_key` is returned in the POST media/upload response when a `media_category` is specified. Type: string Example: `3_931236738554519552` | +| description _optional_ | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` | +| file\_name _optional_ | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` | +| name _optional_ | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` | +| poster\_media\_key _optional_ | Specify a poster image for the video using the `media_key` of an uploaded image. If not specified, the first frame will be used. **Note**: Can only be used with videos. Type: string Example: `3_890599134483242005` | +| title _optional_ | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "3_931236738554519552" + } + }, + "data": { + "tweeted": false, + "name": null, + "file_name": null, + "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg", + "media_category": "TWEET_IMAGE", + "media_key": "3_931236738554519552", + "created_at": "2017-11-16T19:05:14Z", + "media_status": "TRANSCODE_COMPLETED", + "media_type": "IMAGE", + "updated_at": "2017-11-16T19:05:23Z", + "deleted": false + } +} +``` + +Update the specified media library object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key _required_ | A reference to the media library object you are operating with in the request. Type: string Example: `16_844800354743074820` | +| description _optional_ | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` | +| file\_name _optional_ | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` | +| name _optional_ | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` | +| poster\_media\_key _optional_ | Specify a poster image for the video using the `media_key` of an uploaded image. **Note**: Can only be used with videos. Type: string Example: `3_885003359340375465` | +| title _optional_ | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "16_844800354743074820", + "title": "cat GIF", + "description": "in space" + } + }, + "data": { + "tweeted": true, + "duration": null, + "name": null, + "file_name": null, + "description": "in space", + "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4", + "media_category": "TWEET_GIF", + "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg", + "poster_media_key": "3_844800354743074820", + "media_key": "16_844800354743074820", + "created_at": "2017-10-20T09:51:54Z", + "media_status": "TRANSCODE_COMPLETED", + "title": "cat GIF", + "media_type": "GIF", + "aspect_ratio": "125:79", + "updated_at": "2017-10-23T06:37:56Z", + "deleted": false + } +} +``` + +Delete the specified media library object belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| media\_key _required_ | A reference to the media library object you are operating with in the request. Type: string Example: `7_860318603387600896` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "media_key": "7_860318603387600896" + } + }, + "data": { + "tweeted": true, + "duration": 14330, + "name": "mountains-on-ads.x.com", + "file_name": "mountains.mp4", + "description": "", + "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4", + "media_category": "TWEET_VIDEO", + "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg", + "poster_media_key": "3_860318839740915712", + "media_key": "7_860318603387600896", + "created_at": "2017-05-05T02:21:53Z", + "media_status": "TRANSCODE_COMPLETED", + "title": "uploaded on ads.x.com", + "media_type": "VIDEO", + "aspect_ratio": "16:9", + "updated_at": "2017-05-05T02:26:58Z", + "deleted": true + } +} +``` + +### Poll Cards + + + +#### GET accounts/:account\_id/cards/poll + +Retrieve details for some or all poll cards associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_ids _optional_ | Scope the response to just the desired poll cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `57i77` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| q _optional_ | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` | +| sort\_by _optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | +| with\_total\_count _optional_ | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_type": "poll", + "card_ids": [ + "57i77" + ], + "account_id": "18ce54d4x5t" + } + }, + "next_cursor": null, + "data": [ + { + "video_poster_height": "9", + "name": "best coast poll", + "start_time": "2018-01-09T04:51:34Z", + "first_choice": "East", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap", + "content_duration_seconds": "8", + "second_choice": "West", + "end_time": "2018-01-16T04:51:34Z", + "id": "57i77", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4", + "created_at": "2018-01-09T04:51:34Z", + "duration_in_minutes": "10080", + "card_uri": "card://950590850777497601", + "updated_at": "2018-01-09T04:51:34Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_POLLS" + } + ] +} +``` + +Retrieve a specific poll card associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the poll card you are operating with in the request. Type: string Example: `57i8t` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t` + +#### Example Response + +```text +{ + "request": { + "params": { + "card_type": "poll", + "card_id": "57i8t", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "name": "text only poll", + "start_time": "2018-01-09T05:03:05Z", + "first_choice": "Morning", + "second_choice": "Evening", + "end_time": "2018-01-11T05:03:05Z", + "id": "57i8t", + "created_at": "2018-01-09T05:03:05Z", + "duration_in_minutes": "2880", + "card_uri": "card://950593749658189824", + "updated_at": "2018-01-09T05:03:05Z", + "deleted": false, + "card_type": "TEXT_POLLS" + } +} +``` + +#### POST accounts/:account\_id/cards/poll + +Create a new poll card associated with the specified account. This endpoint supports creating poll cards with either an image, a video, or no media. Polls with media are referred to as Media Forward Polls. + +**Note**: The Media Forward Polls product is in beta and requires the `PROMOTED_MEDIA_POLLS` account feature. + +**Note**: It is not possible to update (PUT) poll cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| duration\_in\_minutes _required_ | The amount of time (in minutes) the poll will remain open. After the specified `duration_in_minutes`, the poll will close and votes will no longer be accepted. This corresponds to `end_time` in the response. **Note**: This starts as soon as the card is created and not when it is added to a Tweet. Type: int Min, Max: `5`, `10080` | +| first\_choice _required_ | The first poll choice. Maximum length: 25 characters. Type: string Example: `One` | +| name _required_ | The name for the card. Type: string Example: `poll card` | +| second\_choice _required_ | The second poll choice.Maximum length: 25 characters. Type: string Example: `Two` | +| fourth\_choice _optional_ | The fourth poll choice. Maximum length: 25 characters. **Note**: The first, second, and third choices must be set when using this parameter. Type: string Example: `Four` | +| media\_key _optional_ | The `media_key` of a media library image or video which will be used in this card. This is a write-only field. In the response, the API will provide a X URL for this media. **Note**: The image or video must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. | +| third\_choice _optional_ | The third poll choice. Maximum length: 25 characters. **Note**: The first and second choices must be set when using this parameter. Type: string Example: `Three` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll` + +#### Example Response + +```text +{ + "request": { + "params": { + "first_choice": "East", + "name": "best coast poll", + "second_choice": "West", + "media_key": "13_950589518557540353", + "duration_in_minutes": 10080 + } + }, + "data": { + "video_poster_height": "9", + "name": "best coast poll", + "start_time": "2018-01-09T04:51:34Z", + "first_choice": "East", + "video_height": "9", + "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap", + "content_duration_seconds": "8", + "second_choice": "West", + "end_time": "2018-01-16T04:51:34Z", + "id": "57i77", + "video_width": "16", + "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4", + "created_at": "2018-01-09T04:51:34Z", + "duration_in_minutes": "10080", + "card_uri": "card://950590850777497601", + "updated_at": "2018-01-09T04:51:34Z", + "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg", + "video_poster_width": "16", + "deleted": false, + "card_type": "VIDEO_POLLS" + } +} +``` + +Permanently delete the specified poll card belonging to the current account. + +Note: This is a hard delete. As a result, it is not possible to retrieve deleted cards. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| card\_id _required_ | A reference to the poll card you are operating with in the request. Type: string Example: `57i9t` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t` + +#### Example Response + +```text +{ + "data": { + "name": "poll with image", + "start_time": "2018-01-09T05:10:51Z", + "id": "57i9t", + "created_at": "2018-01-09T05:10:51Z", + "updated_at": "2018-01-09T05:11:04Z", + "deleted": true, + "card_type": "IMAGE_POLLS" + }, + "request": { + "params": { + "card_id": "57i9t", + "card_type": "poll", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Preroll Call To Actions + + + +#### GET accounts/:account\_id/preroll\_call\_to\_actions + +Retrieve details for some or all preroll Call-To-Actions (CTAs) associated with line items under the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| line\_item\_ids _optional_ | Scope the response to just the preroll CTAs associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8v53k` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` | +| preroll\_call\_to\_action\_ids _optional_ | Scope the response to just the desired preroll CTAs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8f0` | +| sort\_by _optional_ | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | +| with\_total\_count _optional_ | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k` + +#### Example Response + +```text +{ + "request": { + "params": { + "account_id": "18ce54d4x5t", + "line_item_ids": [ + "8v53k" + ] + } + }, + "next_cursor": null, + "data": [ + { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + } + ] +} +``` + +Retrieve a specific Call-to-Action (CTAs) associated with this account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id _required_ | A reference to the preroll call to action you are operating with in the request. Type: string Example: `8f0` | +| with\_deleted _optional_ | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0` + +#### Example Response + +```text +{ + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "account_id": "18ce54d4x5t" + } + }, + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + } +} +``` + +#### POST accounts/:account\_id/preroll\_call\_to\_actions + +Set the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| call\_to\_action _required_ | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` | +| call\_to\_action\_url _required_ | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` | +| line\_item\_id _required_ | A reference to the line item you are operating with in the request. Type: string Example: `8v53k` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com` + +#### Example Response + +```text +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-07-07T19:28:40Z", + "deleted": false + }, + "request": { + "params": { + "line_item_id": "8v53k", + "call_to_action": "VISIT_SITE", + "call_to_action_url": "https://www.x.com", + "account_id": "18ce54d4x5t" + } + } +} +``` + +Update the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id _required_ | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` | +| call\_to\_action _optional_ | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` | +| call\_to\_action\_url _optional_ | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW` + +#### Example Response + +```text +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "WATCH_NOW", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-09-09T05:51:26Z", + "deleted": false + }, + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "call_to_action": "WATCH_NOW", + "account_id": "18ce54d4x5t" + } + } +} +``` + +Delete the specified preroll Call-to-Action (CTA) belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| preroll\_call\_to\_action\_id _required_ | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0` + +#### Example Response + +```text +{ + "data": { + "line_item_id": "8v53k", + "call_to_action_url": "https://www.x.com", + "call_to_action": "VISIT_SITE", + "id": "8f0", + "created_at": "2017-07-07T19:28:40Z", + "updated_at": "2017-08-30T06:08:21Z", + "deleted": true + }, + "request": { + "params": { + "preroll_call_to_action_id": "8f0", + "account_id": "18ce54d4x5t" + } + } +} +``` + +### Scheduled Tweets + + + +#### GET accounts/:account\_id/scheduled\_tweets + +Retrieve details for some or all Scheduled Tweets associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| count _optional_ | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` | +| cursor _optional_ | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-j3cn6n40` | +| user\_id _optional_ | Specify the user to retrieve Scheduled Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: long Example: `756201191646691328` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1` + +#### Example Response + +```text +{ + "request": { + "params": { + "count": 1 + } + }, + "data": [ + { + "name": "test name", + "completed_at": "2017-06-18T22:00:05Z", + "text": "where you want to be", + "user_id": "756201191646691328", + "scheduled_status": "SUCCESS", + "id": "875828692081037312", + "nullcast": true, + "created_at": "2017-06-16T21:33:27Z", + "scheduled_at": "2017-06-18T22:00:00Z", + "card_uri": null, + "updated_at": "2017-06-19T18:02:20Z", + "tweet_id": "876560168963645440", + "media_keys": [] + } + ], + "next_cursor": "c-j41uw400" +} +``` + +Retrieve a specific Scheduled Tweet associated with the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id _required_ | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `917438609065623552` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552` + +#### Example Response + +```text +{ + "request": { + "params": { + "scheduled_tweet_id": "917438609065623552" + } + }, + "data": { + "name": null, + "completed_at": null, + "text": "", + "user_id": "756201191646691328", + "scheduled_status": "SCHEDULED", + "id": "917438609065623552", + "nullcast": true, + "created_at": "2017-10-09T17:16:24Z", + "scheduled_at": "2018-01-01T00:00:00Z", + "card_uri": null, + "updated_at": "2017-10-09T17:16:24Z", + "tweet_id": null, + "media_keys": [ + "3_917438348871983104" + ] + } +} +``` + +#### POST accounts/:account\_id/scheduled\_tweets + +Create a Scheduled Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_at _required_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). **Note**: Tweets can only be scheduled up to one year in the future. **Note**: Tweets should only be scheduled at minute-granularity; seconds will be ignored. Type: string Example: `2017-12-31T23:59:00Z` | +| as\_user\_id _required_ | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: long Example: `756201191646691328` | +| text _sometimes required_ | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `just setting up my twttr` | +| card\_uri _optional_ | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://855591459410511943` | +| media\_keys _optional_ | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` | +| nullcast _optional_ | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` | +| name _optional_ | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01` + +#### Example Response + +```text +{ + "request": { + "params": { + "media_keys": [ + "3_917438348871983104" + ], + "scheduled_at": "2018-01-01T00:00:00Z", + "as_user_id": 756201191646691328 + } + }, + "data": { + "name": null, + "completed_at": null, + "text": "", + "user_id": "756201191646691328", + "scheduled_status": "SCHEDULED", + "id": "917438609065623552", + "nullcast": true, + "created_at": "2017-10-09T17:16:24Z", + "scheduled_at": "2018-01-01T00:00:00Z", + "card_uri": null, + "updated_at": "2017-10-09T17:16:24Z", + "tweet_id": null, + "media_keys": [ + "3_917438348871983104" + ] + } +} +``` + +Update the specified Scheduled Tweet belonging to the current account. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id _required_ | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` | +| card\_uri _optional_ | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://875146925316386347` | +| media\_keys _optional_ | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` | +| nullcast _optional_ | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` | +| scheduled\_at _optional_ | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). Type: string Example: `2017-12-31T23:59:59Z` | +| text _optional_ | The text of your status update. Type: string Example: `just setting up my twttr` | +| name _optional_ | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` | + +#### Example Request + +`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice` + +#### Example Response + +```text +{ + "request": { + "params": { + "scheduled_tweet_id": "875057751231037440", + "text": "winter solstice" + } + }, + "data": { + "name": null, + "completed_at": null, + "scheduled_status": "SCHEDULED", + "text": "winter solstice", + "user_id": "756201191646691328", + "id": "875057751231037440", + "nullcast": true, + "created_at": "2017-06-14T18:30:00Z", + "scheduled_at": "2017-12-21T00:00:00Z", + "card_uri": null, + "updated_at": "2017-06-14T18:30:00Z", + "tweet_id": null, + "media_keys": [] + } +} +``` + +Permanently delete the specified Scheduled Tweet belonging to the current account. + +**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Scheduled Tweets. + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| scheduled\_tweet\_id _required_ | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` | + +#### Example Request + +`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776` + +#### Example Response + +```text +{ + "request": { + "params": { + "scheduled_tweet_id": 875064008595787776 + } + }, + "data": { + "name": null, + "completed_at": null, + "scheduled_status": "DELETED", + "text": "hello, world", + "user_id": "756201191646691328", + "id": "875064008595787776", + "nullcast": true, + "created_at": "2017-06-14T18:54:52Z", + "scheduled_at": "2017-06-15T00:00:00Z", + "card_uri": null, + "updated_at": "2017-06-14T19:01:16Z", + "tweet_id": null, + "media_keys": [] + } +} +``` + +### Tweet Previews + + + +#### GET accounts/:account\_id/tweet\_previews + +Preview published, scheduled, or draft Tweets. + +- Supports previewing _multiple_ Tweets—up to 200—in a single API request +- Accurate, up-to-date rendering of Tweet layout and style +- Supports all the latest formats and card types +- Returns an iframe + +#### Resource URL + +`https://ads-api.x.com/12/accounts/:account_id/tweet_previews` + +#### Parameters + +| Name | Description | +| :-- | :-- | +| account\_id _required_ | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` | +| tweet\_ids _required_ | A comma-separated list of identifiers. Up to 200 IDs may be provided. **Note**: The IDs should correspond to the specified `tweet_type`. For example, if a Scheduled Tweet ID is passed in and `tweet_type=PUBLISHED` is specified, a preview for that ID will not be returned. Type: long Example: `1122911801354510336,1102836745790316550` | +| tweet\_type _required_ | The Tweet type for the specified `tweet_ids`. Type: enum Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED` | + +#### Example Request + +`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED` + +#### Example Response + +```text +{ + "request": { + "params": { + "tweet_ids": [ + "1122911801354510336", + "1102836745790316550" + ], + "tweet_type": "PUBLISHED", + "account_id": "18ce54d4x5t" + } + }, + "data": [ + { + "tweet_id": "1122911801354510336", + "preview": "