Creatives

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. Image, GIF, or video creatives are uploaded using either the 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

For additional details on cards, please see the Cards page. The Promoted Video page provides details on associating videos with cards or Tweets.

Cards

The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns. Note: once Tweeted, card details are publicly visible. This may include information about the user who owns the card.

Image

The following image specifications apply to assets used in Cards. 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
Poll: 1.91:1
Image Conversation: 1.91:1
Image Direct Message: 1.91:1

We support the following image formats: .bmp, .jpeg, and .png.

Video

The following video specifications apply to assets used in Cards. We support the following width:height aspect ratios.

Video Website: 16:9 and 1:1
Video App Download: 16:9 and 1:1
Poll: 16:9
Video Conversation: 16:9
Video Direct Message: 16:9

Promoted Video

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 and in the following cards:

First, upload the video using the POST media/upload (chunked) 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 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

Video App Download and Video Conversation cards support the ability to add a poster images. Upload an image to use in these cards using the POST media/upload endpoint. Create the card using one of the following endpoints:

using the video’s id and, optionally, the image’s media_id (for the poster image). Finally, create the Tweet using the POST accounts/:account_id/tweet endpoint. Cards are attached to Tweets using the card_uri parameter.

General Information

For detailed guidance on video uploading through the API, please see the Video Upload Guide. Videos can also be promoted as pre-roll assets. See the Video Views Pre-roll Objective Guide 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) 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.
Uploaded video should be either mp4 or mov.
Uploaded video generally processes quickly, but processing times can vary depending on video length and file size.
Uploaded poster images should be in png or jpg format. There are no aspect ratio or size requirements, but the poster image will be adjusted to fit the video player.

Guides

Scheduled Tweets

Introduction

Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement. The full set of functionality provided by the Scheduled Tweets API endpoints are listed below:

Create, modify and view newly scheduled Tweets
Associate a Scheduled Tweet with a line item
Query and manage existing scheduled Tweets
Once a Scheduled Tweet goes live, retrieve the live Tweet id

API Endpoints

The entire set of endpoints related to the above functionality is listed below:

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:

Scheduled Tweet Create:

Validate that the authenticated user has access to create organic Tweets for a given @handle Promoted-Only Tweet create privileges requires authenticated user to be an account user with Tweet composer permissions
Validate that there are no more than 30 Tweets that are scheduled to be created within a 15 minute window of the scheduled_at time. A SCHEDULED_TWEET_LIMIT_EXCEEDED error message indicates that too many Scheduled Tweets have been scheduled within the same future, 15 minute time frame. Advertisers will need to remove an existing Scheduled Tweet or move the scheduled_at time earlier or later.

Scheduled Tweet goes “live”:

These validation rules are run at the scheduled_at time and are identical to those applied on regular Tweet creation in the API. For example, a Scheduled Tweet will not go live and the scheduled_status will be set to FAILED if the Scheduled Tweet contains both an image and a gif

Workflow

Create a new Scheduled Tweet A new Scheduled Tweet can be created using the POST accounts/:account_id/scheduled_tweets endpoint. This endpoint has the following required parameters, scheduled_at time along with the Tweet text if no media entities are included in the Tweet. In addition, this endpoint provides a few additional options that allow you to create a scheduled Tweet on behalf of another @handle via the as_user_id param along with the ability to add a card (card_uri) and any media (media_ids). Note, a Tweet can only contain entities of the same type, i.e., either Video, Gif or Image. The nullcast param controls whether the Tweet is a “Promoted-Only” Tweet or not. All newly created Scheduled Tweets are “Promoted-Only” (nullcast=true) by default. If nullcast=false then an Organic Scheduled Tweet is created 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!'

This will create the following Scheduled Tweet:

{
  "request": {
    "params": {
      "text": "Happy Holidays!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Happy Holidays!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Once this Scheduled Tweet goes live, the tweet_id field will be populated with the “live” Tweet’s ID. View a Scheduled Tweet The 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

{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}

A sample view of the newly created Scheduled Tweet is shown above Associate a Scheduled Tweet with a line item While Scheduled Tweets can be used to create Organic Tweets, we also allow partners to create a “Promoted-Only” (nullcast=true) Tweet either one of which can be associated with a line item. In order to facilitate this, we provide a POST accounts/:account_id/scheduled_promoted_tweets endpoint as well. This endpoint only allows a single Promoted Scheduled Tweet to be associated with a line item in a single API call. In order to associate multiple Scheduled Tweets to the same line item, multiple API calls are necessary. 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'

{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}

This endpoint only creates an association between a given Scheduled Tweet and a line item. Once the campaign/line item flight dates are current, the line item with automatically start serving the corresponding “live” Tweet. While we do validate during this step that the Scheduled Tweet is in the SCHEDULED state, and that the given Scheduled Tweet is valid for the given objective, no other validations are run. Any remaining validation rules that apply to the line item and Scheduled Tweet are run when the Tweet goes “live” In order to ensure that there are no issues with campaign serving it is recommend that the Scheduled Tweet be scheduled_at a time prior to the campaign/line item flight dates. For example, let’s say the Scheduled Tweet is set to go live after the campaign start date (and that there is only a single Tweet associated with a single line item), then the campaign will be ACTIVE, however given that the Scheduled Tweet is not live yet, there will be no creatives available for serving. Scheduled Tweet Management The remaining sets of endpoints allow API consumers to manage all their Scheduled Tweets and Scheduled Promoted Tweets. These APIs can be used to either return a list of all Scheduled Tweets optionally filtered by a given state as well as lookup a given Scheduled Tweet by its id.

What happens when a Scheduled Tweet goes live?

Once a given Scheduled Tweet is about to go live, or in other words at the scheduled_at time, the following updates are made:

The “live” Tweet is created however this may have a latency of upto 1 second
The tweet_id is added to the following entities:
Scheduled Tweet
Promoted Scheduled Tweet
A new Promoted Tweet entity is created

Best Practices

The following best practices are recommended when creating or promoting Scheduled Tweets:

Ensure that the Tweet is valid when creating the Scheduled Tweet (for example, a Tweet can only have either an Image, Video or Gif and not any combination of the three)
Ensure that the campaign flight dates (i.e., the start_time and end_time) align with the scheduled_at time for the Scheduled Tweet
Scheduled Tweets should not be scheduled for more than one year in the future (365 days)
Tweet preview is currently not supported for Scheduled Tweets (this is ability to preview Scheduled Tweets prior to creation)

Media Library

Introduction

The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in Tweets and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.

API Endpoints

POST media/upload or POST media/upload (chunked) (upload media)
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 endpoint or the POST media/upload (chunked) set of endpoints. (See the Chunked media upload guide for details on our multi-part upload process.)

twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"

{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

Next, using the media ID, add the media to the ads account’s library using the 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"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "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
   }
}

Note: Tweeting images, GIFs, or videos directly after the upload also adds media to the library.

Request Parameters

All Media Library POST requests require a media identifier. This value is returned during the upload step. When using the media_id, as in the example above, a media_category must also be specified. There are four possible category values: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE, and TWEET_VIDEO. Optionally, name and file_name values can be set for objects in the Media Library. These attributes help users distinguish between media variants in the library. For videos, it’s also possible to set a title and a description. They values are intended to be passed as the video_title and video_description request parameters with the POST accounts/:account_id/tweet endpoint. In the Tweet, this text appears under the video.

Attributes

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*, Tweet preview*, and 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"

{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "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
   }
}

Tweet 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"

{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"coffee https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"Ads API Internal Test App",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{
         "id":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{
         "followers":false
      },
      "lang":"en"
   },
   "request":{
      "params":{
         "as_user_id":756201191646691328,
         "text":"coffee",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

Website Card All of our cards endpoints support media keys. We will create the website card by referencing the image’s media_key.

twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"

{
  "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"
      }
    }
  ]
}

We then associate this card with a Tweet using its card_uri.

Identifying Cards

Introduction

Cards are customizable ad formats that use media and that can be associated with a website, an app, or with calls to action to drive certain user engagements, such as starting a Direct Message. They can be appended to Tweets, Scheduled Tweets, or Draft Tweets. 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. 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.

Identifying Tweets with card_uri

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

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "Ads API Internal Test App",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracking a card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

If using the Standard API, use include_card_uri=true in the request. Regardless of which endpoint is used, the card_uri response attribute will only be rendered if the Tweet was created using a card URI. For scheduled and draft Tweet objects, the response will always include the card_uri response attribute.

Identifying Tweets with preview_url

For Tweets created by including the preview URL as part of the Tweet’s text, the URL can be found in entities[“urls”][i][“expanded_url”] (the text field includes a shortened t.co URL), where i is an array index (a Tweet can contain multiple URLs). For scheduled and draft Tweet objects, the preview URL will always appear in the text field.

Fetching cards

To retrieve additional information about a specific card, we provide two endpoints: GET accounts/:account_id/cards/all and GET accounts/:account_id/cards/all/:card_id. The former allows a card to be fetched by card_uri and the latter by the card’s ID. The card’s ID is found at the end of the preview_url. In the example above, the ID is 68w3s.

Identifying Media

Introduction

Media—images, GIFs, and videos—can be added to Tweets and cards. In addition, videos can be used as pre-roll assets and images can be promoted on the X Audience Platform. This section describes how to find media references across these entities. 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.

Images

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"]`
Scheduled Tweet	Both	`media_ids` and `media_keys`
Draft Tweet	Both	`media_ids` and `media_keys`
Account Media	None
Media Library	Both	`media_id` and `media_key`

Image cards and Account Media images do not include a reference any media identifier. Tweets only include media IDs. Scheduled and Draft Tweets include both the media ID and media key. The Media Library returns both, too. For Tweets, the id and id_str fields in the object within the entities[“media”] array correspond to the media ID. In cases where a Tweet includes multiple images, the references to each media entity can only found in extended_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
Draft Tweet	None
Account Media	`media_url`	.jpg
Media Library	`media_url`	.jpg

* This URL locations depend on whether the Tweet contains a single image or multiple images. All image cards include an image response attribute that contains the X image URL. (For image app download cards, the name is wide_app_image.) For Tweets, the media URL location depends on both the type of media and the endpoint being used. For Tweets with a single image, the URL can be found in entities[“media”][0][“media_url”]. This is true for both the Ads API and the Standard API. When Tweets contain multiple images, however, the URLs can only be found extended_entities[“media”][i][“media_url”]. This is only available in the Standard API.

Videos

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"]`
Scheduled Tweet	Both	`media_ids` and `media_keys`
Draft Tweet	Both	`media_ids` and `media_keys`
Account Media	Media key	`video_id`
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. 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
Draft Tweet	None
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

It’s sometimes necessary to retrieve additional information about a media asset. One use case, for video cards, is retrieving the mp4 URL instead of the vmap one. This is available in the Media Library. For details on the available information, see our Media Library Guide. Most assets belonging to the ads account’s FULL promotable user can be found in the library. There are some exceptions, though. Fetching media As stated above, image cards do not contain references to either media IDs or media keys. As a result, it’s not possible to fetch their assets through the Media Library. This is also true for Account Media images. Video cards require that the video asset be part of the Media Library (or the Videos resource before it) prior to creating it. As a result, these assets will always be retrievable in the Media Library. This is also true for Account Media PREROLL assets. 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
Scheduled Tweets	Yes
Draft Tweets	Yes
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. Interactions with Account Media There are two cases where media assets added to the library are automatically added to the Account Media resource.

When an AMPLIFY_VIDEO asset is added to the Media Library, it is automatically added as an Account Media asset as a PREROLL creative type.
When images that have specific dimensions (see “Creative Types” in our enumerations page) are added to the Media Library, they are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions.

Tweets

Introduction

The X Ads API supports three types of Tweets: published, scheduled, and draft.

Nullcasted Tweets

Tweets may either be nullcasted (a.k.a. “Promoted-only”) or organic. Nullcasted Tweets, once published, do not appear in the user’s public timeline, though they are public. Organic Tweets, on the other hand, are served to the user’s followers and do appear in the user’s public timeline. Creating Tweets Each of the three Tweet create endpoints supports a Boolean nullcast parameter that gives the API user the option to create nullcasted or organic Tweets. Nullcasted Tweets can be created by the user or by anyone who has permission to create Tweets on the user’s behalf. Organic Tweets can only be created by the full promotable user. Updating Tweets It is possible to update the nullcast property for scheduled and draft Tweets. For scheduled Tweets, edits can be made until the Tweet’s scheduled_at time. Draft Tweets can be edited indefinitely. Once published, though, it’s not possible to change a Tweet from nullcasted to organic or vice versa.

Promoting Tweets

Only published and scheduled Tweets may be promoted. These can either be nullcasted or organic; there’s no restriction. An advertiser may promote their own Tweets or another user’s Tweets as long as they’ve obtained permission to do so. (See: Promoting another user’s Tweets for more information.) Multiple Tweets can be promoted in a single campaign. Similarly, a single Tweet may be promoted in one or more campaigns. To promote published Tweets, use the POST accounts/:account_id/promoted_tweets endpoint. This associates published Tweets with a line item. To promote scheduled Tweets, use the POST accounts/:account_id/scheduled_promoted_tweets endpoint.

Tweet IDs

Published, scheduled, and draft Tweet IDs are numeric—they are 64-bit unsigned integers. For example, the following published Tweet’s ID is 1166476031668015104. 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"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

In addition to the Tweet ID and the line item ID, which were passed into the create request, the response includes an id field with a value of 3qw1q6, which is the promoted Tweet ID.

Carousels

Introduction

The X Ads API supports creating and retrieving video carousels and image carousels. The carousel is a card type that can contain between 2 and 6 media assets. The carousel card can direct a user to a website or encourage them to install a mobile app. For more information about carousels, their benefits, best practices, and FAQs, see our Carousel Ads on X page. A carousel, like any other card type, can be used in Tweets and those Tweets can then be promoted. The workflow is the same as what you’re already used to:

Upload media
Create the card
Create the Tweet
Promote the Tweet

The only difference is with how the card is created. While other card create requests accept query parameters, carousel card create requests only accept JSON POST bodies.

Endpoints

The Ads API supports creating and retrieving carousels. To create a carousel—any kind—use the POST accounts/:account_id/cards endpoint. To retrieve carousels, use the GET accounts/:account_id/cards endpoint.

JSON POST Body

Carousels are created using two components. The first specifies the media assets that will be used. The second specifies information about either the website or the app. Specifically, a carousel card is created by using the following components, in order:

One SWIPEABLE_MEDIAcomponent, which accepts an array of media keys
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.

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

As a reminder, you can obtain media keys by making a request to the GET accounts/:account_id/media_library endpoint. 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.

{
  "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"
      }
    }
  ]
}

App destination objects within BUTTON components require a country code and at least one app identifier. They optionally accept deep links. For a description of these fields, see the reference documentation. Putting this together, an example app carousel JSON POST body is shown below.

{
  "name": "app carousel",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

Example

This section demonstrates how to create a video website carousel card and how to use it in a Tweet. As mentioned above, the workflow is the same as what you’re already used to: upload media, create the card, create the Tweet. The only difference is how the card is created. Media To start, either upload new media assets or use existing ones. For details on how to upload new media assets and add them to the Media Library, see our Media Library Guide. Once your media assets are in the Media Library, fetch them using the GET accounts/:account_id/media_library endpoint. Use the media_type request parameter to scope the results to a particular media type.

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Sunrise",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "snow",
      "file_name": "snow.mp4",
      "description": "Two, three, and to the four",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "One",
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

Carousel Creation Use the 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.

$ 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"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "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/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

Notice that like with other cards, the carousel card response includes a card_uri, which will be used when creating a Tweet. Tweet Use the POST accounts/:account_id/tweet endpoint to create your Tweet. Use the card_uri from the previous request. (Response truncated for readability.)

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "Ads API Internal Test App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "Swipe",
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Tweet Previews Use the GET accounts/:account_id/tweet_previews endpoint to see your Tweet.

creative-metadata-tagging

Introduction

This guide is for creative partners, agencies and creative developers to tag assets used within X campaigns to better understand individual asset value and performance. Note: Media assets must only be tagged by the partner or developer creating the media asset. If the user of the media asset did not create the media asset, do not implement metadata tagging. Creative Metadata Tagging provides attribution of images and videos created by Creative Partners wherever the asset is uploaded to X, or whomever the entity that is uploading the asset. To create the connection between the creative asset and the creative partner, the XMP standard is used.

Tagging Creative Assets

The following table shows the identifier types currently available in each image-related resource’s response as well as the corresponding attribute name(s). A tagging tool is needed to tag creative assets. ExifTool, a platform-independent Perl library plus a command-line application for reading, writing, and editing meta information, is recommended. See all supported file types. Follow the provided instructions to install ExifTool. There are also software packages offered by Homebrew to further simplify the installation by providing the exiftool install command for macOS and Linux. Confirm your tool is properly installed by entering exiftool -ver in the command line to return the tool’s version number. Learn more about ExifTool command parameters in ExifTool documentation. Creative partners can assign metadata tags on new or existing creative assets with their X app_id to the contributor XMP tag, and date tag. The creative assets will follow the existing size restrictions when Uploading Media. Note: X’s use of the contributor XMP tag ensures metadata captures values for campaigns on X exclusively. exiftool -contributor="<YOUR APP ID>" -creative_file.jpg exiftool -date="<date>" -creative_file.jpg The app_id can be found in the Developer Portal under Projects & Apps. Example: 16489123 The following example adds app_id as the contributor tag and date as the date tag for an image:

app_id:858382169

date:2022-03-13

creative_file: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 image files updated

exiftool -date=2022-03-13 eiffel_tower.jpg

  1 image files updated

Verify that your image has been properly tagged: exiftool -xmp:all -G1 <filename> Example: exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        XMP Toolkit            : Image::ExifTool 12.30

[XMP]        Contributor            : 858382169

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

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. 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 for more information. Type: string Example: `8x7v00oow`
sort_by optional	Sorts by supported attribute in ascending or descending order. See 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

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "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. 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

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": 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. 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

{
  "data": {
    "video_id": 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, POST statuses/update, POST accounts/:account_id/scheduled_tweets, or the POST accounts/:account_id/draft_tweets endpoints. Retrieve details for some or all cards associated with the current account. 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. 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 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 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 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

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "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-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. 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

{
  "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-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 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).

{
  "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. 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`	`title` `destination`	string object
`BUTTON`	`label` `destination`	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.)

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

{
  "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 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

{
  "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

{
  "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).

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

{
  "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

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

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

{
  "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": "developer.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://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Developer Platform",
      "website_url": "https://developer.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. 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

{
  "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": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.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. 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 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

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

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

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

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

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

{
  "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, POST statuses/update, or 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. 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 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 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

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

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

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

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

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

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

{
  "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. Note: When adding a video with the AMPLIFY_VIDEO media category to the Media Library, it is automatically available as a PREROLL 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. 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 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 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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
scheduled_at required	The time, expressed in 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. 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. 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

{
  "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. 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. 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, 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

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

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

{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}

Tweets

GET accounts/:account_id/tweets

Retrieve Tweet details for the account’s full promotable user (default) or the user specified in the user_id parameter. This can be any of the promotable users under the account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
tweet_type required	The Tweet type for the specified `tweet_ids`. Type: enum Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`
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 for more information. Type: string Example: `AAAAAFhLRpQLNF-sGBSgAA`
include_mentions_and_replies optional	Whether to filter out mentions and replies from the list of available Tweets. Type: boolean Default: `false` Possible values: `true`, `false`
name optional	An optional query to scope Tweets by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: `dtc`
timeline_type optional	Whether to return nullcasted (a.k.a. “Promoted-only”) Tweets, organic Tweets, or both. Type: enum Default: `NULLCAST` Possible values: `ALL`, `NULLCAST`, `ORGANIC`
trim_user optional	Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet’s author’s user ID. Type: boolean Default: `false` Possible values: `true`, `false`
tweet_ids optional	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, then the `tweet_type` must be `SCHEDULED` in order for that Tweet to be returned in the response. Type: long Example: `1122911801354510336,1102836745790316550`
user_id optional	Specifies the user to scope Tweets to. 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/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

Example Response

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "EVERYONE",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

POST accounts/:account_id/tweet

Create a Tweet for the account’s full promotable user (default) or the user specified in the as_user_id parameter. Both nullcasted (default) and organic Tweet creation is supported. Nullcasted Tweets do not appear in the public timeline and are not served to followers. Either type can be used in campaigns. If the authenticated user is not the FULL promotable user on this account, determine if they have permission to Tweet on behalf this user by making a request to the GET accounts/:account_id/authenticated_user_access endpoint. A permission of TWEET_COMPOSER indicates that the user may use this endpoint to create nullcasted Tweets on behalf of the FULL promotable user. When using the upload.x.com endpoint for media, pass in the same user_id value for the additional_owners parameter as the as_user_id value that you pass in to this endpoint.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tweet

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. 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. 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: `hello, world`
card_uri optional	Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://853503245793641682`
conversation_settings optional	Choose who can reply to this Tweet. Anyone mentioned can always reply. Note: This field will not be returned in the POST request response, but will be returned when making a GET request. Note: This parameter only works in Ads API v8 and above. Type: enum Default: `EVERYONE` Possible values: `EVERYONE`, `FOLLOWING`, `MENTIONED_USERS`
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. Type: string Example: `13_1153584529292270722`
name optional	The name for the Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name`
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Note: Organic Tweets (`nullcast=false`) can only be created for the authenticated user. Type: boolean Default: `true` Possible values: `true`, `false`
trim_user optional	Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet’s author’s user ID. Type: boolean Default: `false` Possible values: `true`, `false`
tweet_mode optional	Whether the response should be in compatibility or extended mode. See this for additional information. Type: string Possible values: `compat`, `extended`
video_cta optional	The CTA for the video. Type: enum Possible values: `VISIT_SITE`, `WATCH_NOW`
video_cta_value optional	The value for the corresponding CTA on the video. Type: string Example: `https://dev.x.com`
video_description optional	The description that appears under the video. Maximum length: 200 characters. Type: string Example: `Integrate with the X advertising platform`
video_title optional	The title (headline) that appears under the video. Maximum length: 70 characters. Type: string Example: `X Ads API`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true

Example Response

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "hello, world",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>Ads API Internal Test App</a>",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "hello, world",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

Update the specified Tweet name belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
tweet_id required	A reference to the Tweet you are operating with in the request. Type: long Example: `994747471329873920`
name optional	The name for the Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name`

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

Example Response

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "new Tweet name",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "new Tweet name",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Sorcerer / Partner Engineer @twitter / Space Traveller | Former evangelist @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

Video Conversation Cards

GET accounts/:account_id/cards/video_conversation

Retrieve details for some or all video conversation cards associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_ids optional	Scope the response to just the desired video conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `5a86h`
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 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 sky`
sort_by optional	Sorts by supported attribute in ascending or descending order. See 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/video_conversation?card_ids=5a86h

Example Response

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Developers",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

Retrieve a specific video conversation card associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: `4i0ya`
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/video_conversation/5a86h

Example Response

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

POST accounts/:account_id/cards/video_conversation

Create a new video conversation card associated with the specified account. See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_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. 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: `#APIs`
first_cta_tweet required	The Tweet text to be used when the first CTA is clicked. Type: string Example: `Ads API`
media_key required	The media key for a video to be used in this card. Note: The video must be in the account’s Media Library. Note: An aspect ratio of 16:9 is required. Type: string Example: `13_1168079965037467209`
name required	The name for the card. Type: string Example: `video conversation card`
thank_you_text required	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Build it`
title sometimes required	The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if `second_cta` is `not` set. Example: `Developers`
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`
poster_media_key optional	The media key for a poster image to be used in this card. If not specified, the first frame will be used. Note: The video must be in the account’s Media Library. Type: long Example: `3_882726458191298561`
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`
thank_you_url optional	The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou`
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. Type: string Example: `3_883112887618682880`
unlocked_video_media_key optional	The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario. Type: string Example: `13_867520357225418752`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=Ads API&name=video conversation card&thank_you_text=Build it&title=Developers&media_key=13_958388276489895936

Example Response

{
  "data": {
    "name": "video conversation card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "video conversation card",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Build it",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "title": "Developers",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

Update the specified video conversation card belonging to the current account. See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/cards/video_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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: `5a86h`
first_cta optional	The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#APIs`
first_cta_tweet optional	The Tweet text to be used when the first CTA is clicked. Type: string Example: `Ads API`
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 a video to be used in this card. Note: The video must be in the account’s Media Library. Note: An aspect ratio of 16:9 is required. Type: string Example: `13_1168079965037467209`
name optional	The name for the card. Type: string Example: `developers card`
poster_media_key optional	The media key for a poster image to be used in this card. If not specified, the first frame will be used. Note: The video must be in the account’s Media Library. Type: long Example: `3_882726458191298561`
thank_you_text optional	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Build it`
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 video 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. Type: string Example: `3_883112887618682880`
unlocked_video_media_key optional	The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario. Type: string Example: `13_867520357225418752`

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

Example Response

{
  "data": {
    "name": "developers card",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Build it",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Developers",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "developers card"
    }
  }
}

Permanently delete the specified video 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/video_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. The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t`
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: `4i0ya`

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

Example Response

{
  "data": {
    "name": "video conversation card",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}

X Ads API

Fundamentals

Resources

Measurement

​Overview

​Cards

​Image

​Video

​Promoted Video

​Promoted Video in Tweets

​Promoted Video in Cards

​General Information

​Guides

​Scheduled Tweets

​Introduction

​API Endpoints

​Scheduled Tweet Management

​Scheduled Promoted Tweets

​Scheduled Tweet View

​Scheduled Tweet Create:

​Scheduled Tweet goes “live”:

​Workflow

​What happens when a Scheduled Tweet goes live?

​Best Practices

​Media Library

​Introduction

​API Endpoints

​Adding to the Library

​Request Parameters

​Attributes

​Usage

​Identifying Cards

​Introduction

​Identifying Tweets with card_uri

​Identifying Tweets with preview_url

​Fetching cards

​Identifying Media

​Introduction

​Images

​Videos

​Media Library

​Tweets

​Introduction

​Nullcasted Tweets

​Promoting Tweets

​Tweet IDs

​Carousels

​Introduction

​Endpoints

​JSON POST Body

​Example

​creative-metadata-tagging

​Introduction

​Tagging Creative Assets

​Questions?

​API Reference

​Account Media

​GET accounts/:account_id/account_media

​Resource URL

​Parameters

​Example Request

​Example Response

​Resource URL

​Parameters

​Example Request

​Example Response

​Resource URL

​Parameters

​Example Request

​Example Response

​Cards

​Resource URL

​Parameters

​Example Request

​Example Response

​Resource URL

​Parameters

​Example Request

​Example Response

​POST accounts/:account_id/cards

Overview

Cards

Image

Video

Promoted Video

Promoted Video in Tweets

Promoted Video in Cards

General Information

Guides

Scheduled Tweets

Introduction

API Endpoints

Scheduled Tweet Management

Scheduled Promoted Tweets

Scheduled Tweet View

Scheduled Tweet Create:

Scheduled Tweet goes “live”:

Workflow

What happens when a Scheduled Tweet goes live?

Best Practices

Media Library

Introduction

API Endpoints

Adding to the Library

Request Parameters

Attributes

Usage

Identifying Cards

Introduction

Identifying Tweets with card_uri

Identifying Tweets with preview_url

Fetching cards

Identifying Media

Introduction

Images

Videos

Media Library

Tweets

Introduction

Nullcasted Tweets

Promoting Tweets

Tweet IDs

Carousels

Introduction

Endpoints

JSON POST Body

Example

creative-metadata-tagging

Introduction

Tagging Creative Assets

Questions?

API Reference

Account Media

GET accounts/:account_id/account_media

Resource URL

Parameters

Example Request

Example Response

Resource URL

Parameters

Example Request

Example Response

Resource URL

Parameters

Example Request

Example Response

Cards

Resource URL

Parameters

Example Request

Example Response

Resource URL

Parameters

Example Request

Example Response

POST accounts/:account_id/cards

Resource URL

Parameters

Components

Example Request