> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-810351b9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Creatives API Reference
> Complete technical reference for all Creatives endpoints in the X Ads API — Cards, Tweets, Media Library, Account Media, Draft Tweets, Polls, Preroll CTAs, Conversation Cards, Scheduled Tweets, and more.
## API Reference
### Account Media
#### GET accounts/:account\_id/account\_media
Retrieve details for some or all account media associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/account_media`
#### Parameters
| Name | Description |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| account\_media\_ids *optional* | Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `3wpx` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` |
| creative\_types *optional* | Scope the response to just the account media that match the specified creative types. More than one creative type may be specified by comma-separating enum values. Type: enum Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| account\_media\_id *required* | A reference to the account media you are operating with in the request. Type: string Example: `2pnfd` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/draft-tweets#post-accounts-account-id-draft-tweets) endpoints.
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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_types *optional* | Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: `IMAGE_APP`, `IMAGE_CAROUSEL_APP`, `IMAGE_CAROUSEL_WEBSITE`, `IMAGE_MULTI_DEST_CAROUSEL_WEBSITE`, `IMAGE_WEBSITE`, `MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP`, `MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE`, `VIDEO_APP`, `VIDEO_CAROUSEL_APP`, `VIDEO_CAROUSEL_WEBSITE`, `VIDEO_MULTI_DEST_CAROUSEL_WEBSITE`, `VIDEO_WEBSITE` |
| card\_id *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: `1044294149527166979,1044301099031658496` |
| card\_uris *optional* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` |
| include\_legacy\_cards *optional* | Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account\_id/cards/:card\_type. See [this developer forum post](https://devcommunity.x.com/t/new-cards-endpoints-and-carousel-ads/145782/6) for additional context. Type: boolean Default: `false` Possible values: `true`, `false` |
| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `dtc` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | The id of the cards. Type: string Example: `1044294149527166979` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/carousels) for a detailed usage example.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards`
#### Parameters
The JSON POST body must include a card `name` and an array of `components`. Components are represented as objects and describe the advertiser-facing attributes of the card.
The following example shows the general structure of the payload (but includes non-working information).
```
{
"name": "some name",
"components": [
{
"type": "TYPE_ENUM",
"key": "value"
}
]
}
```
Additional information on components below.
| Name | Description |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| name *required* | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` |
| components *sometimes required* | Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects |
| slides *sometimes required* | Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array |
#### Components
Every component must include a `type` field which determines the object's schema. The Ads API supports the following component types, grouped into media- and description-based components.
* Media:
* `MEDIA`: single video or image
* `SWIPEABLE_MEDIA`: between 2-6 videos or images
* Description:
* `DETAILS`
* `BUTTON`
Each component has a set of required fields (in addition to the `type` key). These are listed in the following table.
| Component `type` | Field | Value type |
| :---------------- | :---------------------- | :--------------- |
| `MEDIA` | `media_key` | string |
| `SWIPEABLE_MEDIA` | `media_keys` | array of strings |
| `DETAILS` | `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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) two-letter code for the country where the app is sold. Type: string Example: `US` |
| googleplay\_app\_id *sometimes required* | The Google Play application package name. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `com.twitter.android` |
| ios\_app\_store\_identifier *sometimes required* | The iOS app store identifier. **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`. Type: string Example: `333903271` |
| googleplay\_deep\_link *optional* | A deep link into the Android app you're promoting. **Note**: Can only be used if an `googleplay_app_id` has been provided. Type: string |
| ios\_deep\_link *optional* | A deep link into the iOS app you're promoting. **Note**: Can only be used if an `ios_app_store_identifier` has been provided. Type: string |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards`
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| name *optional* | The name for the card. Maximum length: 80 characters. Type: string Example: `component based card` |
| components *optional* | Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`. **Note**: The order of the components is important. Type: array of objects |
| slides *optional* | Use this array of array to update Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with `components`. **Note**: The order of each slide is important. Type: array of array |
#### Example Request
This example updates both the name and removes one of the media\_keys from the components field from the example above.
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | The id of the card to be deleted. Type: string Example: `1044294149527166979` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"card_id": "1321554298900107264"
}
},
"data": [
{
"name": "deep link",
"components": [
{
"type": "SWIPEABLE_MEDIA",
"media_keys": [
"3_1073727809120419840",
"3_1075096386931052545"
]
},
{
"type": "BUTTON",
"label": {
"type": "ENUM",
"value": "OPEN"
},
"destination": {
"type": "APP",
"country_code": "US",
"googleplay_app_id": "com.twitter.android",
"googleplay_deep_link": "twitter://user?screen_name=apimctestface"
}
}
],
"created_at": "2020-10-28T20:47:52Z",
"card_uri": "card://1321554298900107264",
"id": "1321554298900107264",
"updated_at": "2020-10-29T20:47:52Z",
"deleted": true,
"card_type": "IMAGE_CAROUSEL_APP"
}
]
}
```
### Cards Fetch
Retrieve multiple cards, by `card_uri`, associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/all`
#### Parameters
| Name | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_uris *required* | Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: `card://1044294149527166979,card://1044301099031658496` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the card you are operating with in the request. Type: string Example: `508pf` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf`
#### Example Response
```
{
"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](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-jh1g0ryb` |
| user\_id *optional* | Specify the user to retrieve Draft Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: string Example: `756201191646691328` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1`
#### Example Response
```
{
"request": {
"params": {
"count": 1
}
},
"data": [
{
"name" null,
"text": "hello, world",
"user_id": "756201191646691328",
"id": "994791681219231744",
"nullcast": true,
"created_at": "2018-05-11T04:09:53Z",
"card_uri": null,
"updated_at": "2018-05-11T04:09:53Z",
"media_keys": []
}
],
"next_cursor": "c-jh1g0ryb"
}
```
Retrieve a specific Draft Tweet associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`
#### Parameters
| Name | Description |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994788364334325760` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760`
#### Example Response
```
{
"request": {
"params": {
"draft_tweet_id": "994788364334325760"
}
},
"data": {
"name": null,
"text": "#TwitterDev",
"user_id": "756201191646691328",
"id": "994788364334325760",
"nullcast": true,
"created_at": "2018-05-11T03:56:42Z",
"card_uri": "card://958225772740714496",
"updated_at": "2018-05-11T03:56:42Z",
"media_keys": []
}
}
```
#### POST accounts/:account\_id/draft\_tweets
Create a Draft Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets`
#### Parameters
| Name | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| as\_user\_id *required* | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: string Example: `756201191646691328` |
| text *sometimes required* | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `Just setting up my X.` |
| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://960880280705392541` |
| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` |
| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` |
| name *optional* | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.`
#### Example Response
```
{
"request": {
"params": {
"text": "Just setting up my X.",
"as_user_id": "756201191646691328"
}
},
"data": {
"name": null,
"text": "Just setting up my X.",
"user_id": "756201191646691328",
"id": "994747471329873920",
"nullcast": true,
"created_at": "2018-05-11T01:14:13Z",
"card_uri": null,
"updated_at": "2018-05-11T01:14:13Z",
"media_keys": []
}
}
```
Update the specified Draft Tweet belonging to the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`
#### Parameters
| Name | Description |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994747471329873920` |
| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://970582057284129151` |
| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` |
| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` |
| text *optional* | The text of your status update. Type: string Example: `just setting up my twttr` |
| name *optional* | The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` |
#### Example Request
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr`
#### Example Response
```
{
"request": {
"params": {
"draft_tweet_id": 994747471329873920,
"text": "just setting up my twttr"
}
},
"data": {
"name": null,
"text": "just setting up my twttr",
"user_id": "756201191646691328",
"id": "994747471329873920",
"nullcast": true,
"created_at": "2018-05-11T01:14:13Z",
"card_uri": null,
"updated_at": "2018-05-11T01:16:59Z",
"media_keys": []
}
}
```
Permanently delete the specified Draft Tweet belonging to the current account.
**Note**: We **strongly** recommend deleting drafts once a Tweet or Scheduled Tweet has been created using its metadata.
**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Draft Tweets.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`
#### Parameters
| Name | Description |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `994787835663155200` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200`
#### Example Response
```
{
"request": {
"params": {
"draft_tweet_id": "994787835663155200"
}
},
"data": {
"name": null,
"text": "hello, world",
"user_id": "756201191646691328",
"id": "994787835663155200",
"nullcast": true,
"status": "DELETED",
"created_at": "2018-05-11T03:54:36Z",
"card_uri": null,
"updated_at": "2018-05-11T04:07:31Z",
"media_keys": []
}
}
```
#### POST accounts/:account\_id/draft\_tweets/preview/:draft\_tweet\_id
Preview a Draft Tweet on a mobile device.
A successful request sends a notification to every device the authenticated user is logged in to. Clicking on the notification opens a timeline that allows the user to see and interact with the Draft Tweet, enabling them to test auto-play, volume, fullscreen, video website card docking, and other behaviors.
**Note**: On-device previews are only visible to the user who receives the notification.
**Note**: Notifications only get sent to X official apps.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id`
#### Parameters
| Name | Description |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| draft\_tweet\_id *required* | A reference to the Draft Tweet you are operating with in the request. Type: string Example: `996132315829948416` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"draft_tweet_id": "996132315829948416"
}
},
"message": "See @apimctestface's notifications in the X app to preview your Tweet."
}
```
### Image Conversation Cards
**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet), [POST statuses/update](https://developer.x.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update#post-statuses-update), or [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) endpoints.
#### GET accounts/:account\_id/cards/image\_conversation
Retrieve details for some or all image conversation cards associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`
#### Parameters
| Name | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_ids *optional* | Scope the response to just the desired image conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `59woh` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` |
| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh`
#### Example Response
```
{
"request": {
"params": {
"card_type": "image_conversation",
"card_ids": [
"59woh"
],
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
}
]
}
```
Retrieve a specific image conversation card associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`
#### Parameters
| Name | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `59woh` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh`
#### Example Response
```
{
"request": {
"params": {
"card_type": "image_conversation",
"card_id": "59woh",
"account_id": "18ce54d4x5t"
}
},
"data": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
}
}
```
#### POST accounts/:account\_id/cards/image\_conversation
Create a new image conversation card associated with the specified account.
See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`
#### Parameters
| Name | Description |
| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| first\_cta *required* | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` |
| first\_cta\_tweet *required* | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` |
| media\_key *required* | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` |
| name *required* | The name for the card. Type: string Example: `image conversation card` |
| thank\_you\_text *required* | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` |
| second\_cta *sometimes required* | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` |
| second\_cta\_tweet *sometimes required* | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` |
| title *sometimes required* | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` |
| third\_cta *optional* | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` |
| third\_cta\_tweet *sometimes required* | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` |
| fourth\_cta *optional* | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` |
| fourth\_cta\_tweet *sometimes required* | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` |
| unlocked\_image\_media\_key *optional* | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` |
| thank\_you\_url *optional* | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon`
#### Example Response
```
{
"data": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"id": "59woh",
"first_cta_tweet": "stars",
"media_key": "3_957113581522141184",
"created_at": "2018-01-27T04:58:42Z",
"image_display_width": "1280",
"card_uri": "card://923498485702009837",
"title": "Full moon",
"updated_at": "2018-01-27T04:58:42Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"name": "image conversation card",
"first_cta": "#moon",
"image_display_height": "670",
"media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
"thank_you_text": "thanks",
"media_key": "3_957113581522141184",
"account_id": "18ce54d4x5t",
"first_cta_tweet": "stars",
"image_display_width": "1280",
"title": "Full moon",
"card_type": "IMAGE_CONVERSATION"
}
}
}
```
Update the specified image conversation card belonging to the current account.
See [Uploading Media](https://developer.x.com/rest/public/uploading-media) for useful information on uploading images to our endpoints.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`
#### Parameters
| Name | Description |
| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qg` |
| first\_cta *optional* | The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareNow` |
| first\_cta\_tweet *optional* | The Tweet text to be used when the first CTA is clicked. Type: string Example: `I Heart @AdsAPI` |
| second\_cta *optional* | The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string **Note**: Required if `title` is `not` set. Example: `#ShareAgain` |
| second\_cta\_tweet *optional* | The Tweet text to be used when the second CTA is clicked. **Note**: Required if `second_cta` is set. Type: string Example: `I Heart @AdsAPI Again` |
| third\_cta *optional* | The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareMore` |
| third\_cta\_tweet *optional* | The Tweet text to be used when the third CTA is clicked. Type: string **Note**: Required if `third_cta` is set. Example: `I Heart @TwitterDev` |
| fourth\_cta *optional* | The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: `#ShareExtra` |
| fourth\_cta\_tweet *optional* | The Tweet text to be used when the fourth CTA is clicked. Type: string **Note**: Required if `fourth_cta` is set. Example: `I Heart @TwitterDev Again` |
| media\_key *optional* | The media key for an image to be used in this card. **Note**: The image must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: `3_1151345051104991073` |
| name *optional* | The name for the card. Type: string Example: `moon card` |
| thank\_you\_text *optional* | The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: `Thank you` |
| thank\_you\_url *optional* | The URL to be displayed with the thank you text. Type: string Example: `https://example.com/thankyou` |
| title *optional* | The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string **Note**: Required if `second_cta` is `not` set. Example: `Start a conversation` |
| unlocked\_image\_media\_key *optional* | A `media_key` of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. **Note**: The image must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: `3_883112887618682880` |
#### Example Request
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card`
#### Example Response
```
{
"data": {
"name": "moon card",
"id": "59woh",
"created_at": "2018-01-27T04:58:42Z",
"card_uri": "card://923498485702009837",
"updated_at": "2018-01-29T21:04:39Z",
"deleted": false,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"account_id": "18ce54d4x5t",
"card_type": "IMAGE_CONVERSATION",
"card_id": "59woh",
"name": "moon card"
}
}
}
```
Permanently delete the specified image conversation card belonging to the current account.
**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted cards.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the image conversation card you are operating with in the request. Type: string Example: `4i0qe` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe`
#### Example Response
```
{
"data": {
"name": "image conversation card",
"id": "4i0qe",
"created_at": "2017-07-07T00:03:01Z",
"updated_at": "2017-08-23T13:26:23Z",
"deleted": true,
"card_type": "IMAGE_CONVERSATION"
},
"request": {
"params": {
"card_id": "4i0qe",
"card_type": "image_conversation",
"account_id": "18ce54d4x5t"
}
}
}
```
### Media Library
#### GET accounts/:account\_id/media\_library
Retrieve details for some or all media library objects associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/media_library`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `20` Min, Max: `1`, `50` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-1` |
| media\_type *optional* | Scope the response to just the desired media type. Type: enum Possible values: `GIF`, `IMAGE`, `VIDEO` |
| q *optional* | An optional query to scope resource by `name`, `title`, `file_name`, and `description` fields. **Note**: This performs case-insensitive *term* matching. Type: string Min, Max length: `1`, `255` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"count": 1
}
},
"data": [
{
"tweeted": true,
"name": null,
"file_name": "coffee https://t.co/4tcPU9XUon",
"media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
"media_category": "TWEET_IMAGE",
"media_key": "3_908573900237180928",
"created_at": "2017-09-15T06:11:12Z",
"media_status": "TRANSCODE_COMPLETED",
"media_type": "IMAGE",
"updated_at": "2017-11-16T06:00:01Z",
"deleted": false
}
],
"next_cursor": "c-1"
}
```
Retrieve a specific media library object associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `13_909110614026444802` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "13_909110614026444802"
}
},
"data": {
"tweeted": true,
"duration": 39973,
"name": null,
"file_name": "buildings https://t.co/xFdzrHM5QG",
"description": null,
"media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
"media_category": "AMPLIFY_VIDEO",
"poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
"poster_media_key": "3_909110614026444802",
"media_key": "13_909110614026444802",
"created_at": "2017-09-16T17:43:55Z",
"media_status": "TRANSCODE_COMPLETED",
"title": "buildings",
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2017-09-27T13:04:00Z",
"deleted": false
}
}
```
Associate a media object with the current account. For additional details, please see our [Media Library guide](https://developer.x.com/en/docs/ads/creatives/guides/media-library).
**Note**: When adding a video with the `AMPLIFY_VIDEO` media category to the Media Library, it is automatically available as a `PREROLL` [account\_media](https://developer.x.com/en/docs/ads/creatives/api-reference/account-media#get-accounts-account-id-account-media) asset.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/media_library`
#### Parameters
| Name | Description |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| media\_key *required* | The `media_key` for the uploaded content. A `media_key` is returned in the POST media/upload response when a `media_category` is specified. Type: string Example: `3_931236738554519552` |
| description *optional* | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` |
| file\_name *optional* | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` |
| name *optional* | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` |
| poster\_media\_key *optional* | Specify a poster image for the video using the `media_key` of an uploaded image. If not specified, the first frame will be used. **Note**: Can only be used with videos. Type: string Example: `3_890599134483242005` |
| title *optional* | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "3_931236738554519552"
}
},
"data": {
"tweeted": false,
"name": null,
"file_name": null,
"media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
"media_category": "TWEET_IMAGE",
"media_key": "3_931236738554519552",
"created_at": "2017-11-16T19:05:14Z",
"media_status": "TRANSCODE_COMPLETED",
"media_type": "IMAGE",
"updated_at": "2017-11-16T19:05:23Z",
"deleted": false
}
}
```
Update the specified media library object belonging to the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`
#### Parameters
| Name | Description |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `16_844800354743074820` |
| description *optional* | The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video's `description`, use the `video_description` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `This is the description under the video.` |
| file\_name *optional* | The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the `file_name` is not set. Type: string Example: `coffee.jpeg` |
| name *optional* | The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be "Untitled" when the `name` is not set. Type: string Example: `Latte` |
| poster\_media\_key *optional* | Specify a poster image for the video using the `media_key` of an uploaded image. **Note**: Can only be used with videos. Type: string Example: `3_885003359340375465` |
| title *optional* | The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video's `title`, use the `video_title` parameter with the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. **Note**: Can only be used with videos. Type: string Example: `Video title` |
#### Example Request
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "16_844800354743074820",
"title": "cat GIF",
"description": "in space"
}
},
"data": {
"tweeted": true,
"duration": null,
"name": null,
"file_name": null,
"description": "in space",
"media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
"media_category": "TWEET_GIF",
"poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
"poster_media_key": "3_844800354743074820",
"media_key": "16_844800354743074820",
"created_at": "2017-10-20T09:51:54Z",
"media_status": "TRANSCODE_COMPLETED",
"title": "cat GIF",
"media_type": "GIF",
"aspect_ratio": "125:79",
"updated_at": "2017-10-23T06:37:56Z",
"deleted": false
}
}
```
Delete the specified media library object belonging to the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| media\_key *required* | A reference to the media library object you are operating with in the request. Type: string Example: `7_860318603387600896` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"media_key": "7_860318603387600896"
}
},
"data": {
"tweeted": true,
"duration": 14330,
"name": "mountains-on-ads.x.com",
"file_name": "mountains.mp4",
"description": "",
"media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
"media_category": "TWEET_VIDEO",
"poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
"poster_media_key": "3_860318839740915712",
"media_key": "7_860318603387600896",
"created_at": "2017-05-05T02:21:53Z",
"media_status": "TRANSCODE_COMPLETED",
"title": "uploaded on ads.x.com",
"media_type": "VIDEO",
"aspect_ratio": "16:9",
"updated_at": "2017-05-05T02:26:58Z",
"deleted": true
}
}
```
### Poll Cards
#### GET accounts/:account\_id/cards/poll
Retrieve details for some or all poll cards associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/poll`
#### Parameters
| Name | Description |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_ids *optional* | Scope the response to just the desired poll cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `57i77` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` |
| q *optional* | An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters. **Note**: This performs case-insensitive prefix matching. Type: string Example: `night` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77`
#### Example Response
```
{
"request": {
"params": {
"card_type": "poll",
"card_ids": [
"57i77"
],
"account_id": "18ce54d4x5t"
}
},
"next_cursor": null,
"data": [
{
"video_poster_height": "9",
"name": "best coast poll",
"start_time": "2018-01-09T04:51:34Z",
"first_choice": "East",
"video_height": "9",
"video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
"content_duration_seconds": "8",
"second_choice": "West",
"end_time": "2018-01-16T04:51:34Z",
"id": "57i77",
"video_width": "16",
"video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
"created_at": "2018-01-09T04:51:34Z",
"duration_in_minutes": "10080",
"card_uri": "card://950590850777497601",
"updated_at": "2018-01-09T04:51:34Z",
"video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
"video_poster_width": "16",
"deleted": false,
"card_type": "VIDEO_POLLS"
}
]
}
```
Retrieve a specific poll card associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`
#### Parameters
| Name | Description |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the poll card you are operating with in the request. Type: string Example: `57i8t` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t`
#### Example Response
```
{
"request": {
"params": {
"card_type": "poll",
"card_id": "57i8t",
"account_id": "18ce54d4x5t"
}
},
"data": {
"name": "text only poll",
"start_time": "2018-01-09T05:03:05Z",
"first_choice": "Morning",
"second_choice": "Evening",
"end_time": "2018-01-11T05:03:05Z",
"id": "57i8t",
"created_at": "2018-01-09T05:03:05Z",
"duration_in_minutes": "2880",
"card_uri": "card://950593749658189824",
"updated_at": "2018-01-09T05:03:05Z",
"deleted": false,
"card_type": "TEXT_POLLS"
}
}
```
#### POST accounts/:account\_id/cards/poll
Create a new poll card associated with the specified account. This endpoint supports creating poll cards with either an image, a video, or no media. Polls with media are referred to as Media Forward Polls.
**Note**: The Media Forward Polls product is in beta and requires the `PROMOTED_MEDIA_POLLS` account feature.
**Note**: It is not possible to update (PUT) poll cards.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/poll`
#### Parameters
| Name | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| duration\_in\_minutes *required* | The amount of time (in minutes) the poll will remain open. After the specified `duration_in_minutes`, the poll will close and votes will no longer be accepted. This corresponds to `end_time` in the response. **Note**: This starts as soon as the card is created and not when it is added to a Tweet. Type: int Min, Max: `5`, `10080` |
| first\_choice *required* | The first poll choice. Maximum length: 25 characters. Type: string Example: `One` |
| name *required* | The name for the card. Type: string Example: `poll card` |
| second\_choice *required* | The second poll choice.Maximum length: 25 characters. Type: string Example: `Two` |
| fourth\_choice *optional* | The fourth poll choice. Maximum length: 25 characters. **Note**: The first, second, and third choices must be set when using this parameter. Type: string Example: `Four` |
| media\_key *optional* | The `media_key` of a media library image or video which will be used in this card. This is a write-only field. In the response, the API will provide a X URL for this media. **Note**: The image or video must be in the account's media library. **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. |
| third\_choice *optional* | The third poll choice. Maximum length: 25 characters. **Note**: The first and second choices must be set when using this parameter. Type: string Example: `Three` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll`
#### Example Response
```
{
"request": {
"params": {
"first_choice": "East",
"name": "best coast poll",
"second_choice": "West",
"media_key": "13_950589518557540353",
"duration_in_minutes": 10080
}
},
"data": {
"video_poster_height": "9",
"name": "best coast poll",
"start_time": "2018-01-09T04:51:34Z",
"first_choice": "East",
"video_height": "9",
"video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
"content_duration_seconds": "8",
"second_choice": "West",
"end_time": "2018-01-16T04:51:34Z",
"id": "57i77",
"video_width": "16",
"video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
"created_at": "2018-01-09T04:51:34Z",
"duration_in_minutes": "10080",
"card_uri": "card://950590850777497601",
"updated_at": "2018-01-09T04:51:34Z",
"video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
"video_poster_width": "16",
"deleted": false,
"card_type": "VIDEO_POLLS"
}
}
```
Permanently delete the specified poll card belonging to the current account.
Note: This is a hard delete. As a result, it is not possible to retrieve deleted cards.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| card\_id *required* | A reference to the poll card you are operating with in the request. Type: string Example: `57i9t` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t`
#### Example Response
```
{
"data": {
"name": "poll with image",
"start_time": "2018-01-09T05:10:51Z",
"id": "57i9t",
"created_at": "2018-01-09T05:10:51Z",
"updated_at": "2018-01-09T05:11:04Z",
"deleted": true,
"card_type": "IMAGE_POLLS"
},
"request": {
"params": {
"card_id": "57i9t",
"card_type": "poll",
"account_id": "18ce54d4x5t"
}
}
}
```
### Preroll Call To Actions
#### GET accounts/:account\_id/preroll\_call\_to\_actions
Retrieve details for some or all preroll Call-To-Actions (CTAs) associated with line items under the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions`
#### Parameters
| Name | Description |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| line\_item\_ids *optional* | Scope the response to just the preroll CTAs associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8v53k` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `200` Min, Max: `1`, `1000` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `8x7v00oow` |
| preroll\_call\_to\_action\_ids *optional* | Scope the response to just the desired preroll CTAs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `8f0` |
| sort\_by *optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](https://developer.x.com/x-ads-api/fundamentals/sorting) for more information. Type: string Example: `created_at-asc` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
| with\_total\_count *optional* | Include the `total_count` response attribute. **Note**: This parameter and `cursor` are exclusive. **Note**: Requests which include `total_count` will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k`
#### Example Response
```
{
"request": {
"params": {
"account_id": "18ce54d4x5t",
"line_item_ids": [
"8v53k"
]
}
},
"next_cursor": null,
"data": [
{
"line_item_id": "8v53k",
"call_to_action_url": "https://www.x.com",
"call_to_action": "VISIT_SITE",
"id": "8f0",
"created_at": "2017-07-07T19:28:40Z",
"updated_at": "2017-07-07T19:28:40Z",
"deleted": false
}
]
}
```
Retrieve a specific Call-to-Action (CTAs) associated with this account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`
#### Parameters
| Name | Description |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *required* | A reference to the preroll call to action you are operating with in the request. Type: string Example: `8f0` |
| with\_deleted *optional* | Include deleted results in your request. Type: boolean Default: `false` Possible values: `true`, `false` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`
#### Example Response
```
{
"request": {
"params": {
"preroll_call_to_action_id": "8f0",
"account_id": "18ce54d4x5t"
}
},
"data": {
"line_item_id": "8v53k",
"call_to_action_url": "https://www.x.com",
"call_to_action": "VISIT_SITE",
"id": "8f0",
"created_at": "2017-07-07T19:28:40Z",
"updated_at": "2017-07-07T19:28:40Z",
"deleted": false
}
}
```
#### POST accounts/:account\_id/preroll\_call\_to\_actions
Set the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions`
#### Parameters
| Name | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| call\_to\_action *required* | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` |
| call\_to\_action\_url *required* | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` |
| line\_item\_id *required* | A reference to the line item you are operating with in the request. Type: string Example: `8v53k` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com`
#### Example Response
```
{
"data": {
"line_item_id": "8v53k",
"call_to_action_url": "https://www.x.com",
"call_to_action": "VISIT_SITE",
"id": "8f0",
"created_at": "2017-07-07T19:28:40Z",
"updated_at": "2017-07-07T19:28:40Z",
"deleted": false
},
"request": {
"params": {
"line_item_id": "8v53k",
"call_to_action": "VISIT_SITE",
"call_to_action_url": "https://www.x.com",
"account_id": "18ce54d4x5t"
}
}
}
```
Update the optional Call-to-Action (CTA) for a `PREROLL_VIEWS` line item.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`
#### Parameters
| Name | Description |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *required* | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` |
| call\_to\_action *optional* | The CTA text for the displayed button within the ad. Type: enum Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW` |
| call\_to\_action\_url *optional* | The URL to redirect the user to when the CTA button is clicked. Type: string Example: `https://www.x.com` |
#### Example Request
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW`
#### Example Response
```
{
"data": {
"line_item_id": "8v53k",
"call_to_action_url": "https://www.x.com",
"call_to_action": "WATCH_NOW",
"id": "8f0",
"created_at": "2017-07-07T19:28:40Z",
"updated_at": "2017-09-09T05:51:26Z",
"deleted": false
},
"request": {
"params": {
"preroll_call_to_action_id": "8f0",
"call_to_action": "WATCH_NOW",
"account_id": "18ce54d4x5t"
}
}
}
```
Delete the specified preroll Call-to-Action (CTA) belonging to the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`
#### Parameters
| Name | Description |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| preroll\_call\_to\_action\_id *required* | A reference to the preroll CTA you are operating with in the request. Type: string Example: `8f0` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`
#### Example Response
```
{
"data": {
"line_item_id": "8v53k",
"call_to_action_url": "https://www.x.com",
"call_to_action": "VISIT_SITE",
"id": "8f0",
"created_at": "2017-07-07T19:28:40Z",
"updated_at": "2017-08-30T06:08:21Z",
"deleted": true
},
"request": {
"params": {
"preroll_call_to_action_id": "8f0",
"account_id": "18ce54d4x5t"
}
}
}
```
### Scheduled Tweets
#### GET accounts/:account\_id/scheduled\_tweets
Retrieve details for some or all Scheduled Tweets associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| count *optional* | Specifies the number of records to try and retrieve per distinct request. Type: int Default: `100` Min, Max: `1`, `200` |
| cursor *optional* | Specifies a cursor to get the next page of results. See [Pagination](https://developer.x.com/x-ads-api/introduction) for more information. Type: string Example: `c-j3cn6n40` |
| user\_id *optional* | Specify the user to retrieve Scheduled Tweets for. Defaults to the `FULL` promotable user on the account when not set. Type: long Example: `756201191646691328` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1`
#### Example Response
```
{
"request": {
"params": {
"count": 1
}
},
"data": [
{
"name": "test name",
"completed_at": "2017-06-18T22:00:05Z",
"text": "where you want to be",
"user_id": "756201191646691328",
"scheduled_status": "SUCCESS",
"id": "875828692081037312",
"nullcast": true,
"created_at": "2017-06-16T21:33:27Z",
"scheduled_at": "2017-06-18T22:00:00Z",
"card_uri": null,
"updated_at": "2017-06-19T18:02:20Z",
"tweet_id": "876560168963645440",
"media_keys": []
}
],
"next_cursor": "c-j41uw400"
}
```
Retrieve a specific Scheduled Tweet associated with the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`
#### Parameters
| Name | Description |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `917438609065623552` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552`
#### Example Response
```
{
"request": {
"params": {
"scheduled_tweet_id": "917438609065623552"
}
},
"data": {
"name": null,
"completed_at": null,
"text": "",
"user_id": "756201191646691328",
"scheduled_status": "SCHEDULED",
"id": "917438609065623552",
"nullcast": true,
"created_at": "2017-10-09T17:16:24Z",
"scheduled_at": "2018-01-01T00:00:00Z",
"card_uri": null,
"updated_at": "2017-10-09T17:16:24Z",
"tweet_id": null,
"media_keys": [
"3_917438348871983104"
]
}
}
```
#### POST accounts/:account\_id/scheduled\_tweets
Create a Scheduled Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets`
#### Parameters
| Name | Description |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| scheduled\_at *required* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). **Note**: Tweets can only be scheduled up to one year in the future. **Note**: Tweets should only be scheduled at minute-granularity; seconds will be ignored. Type: string Example: `2017-12-31T23:59:00Z` |
| as\_user\_id *required* | The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via [ads.x.com](https://ads.x.com/). This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser's. Type: long Example: `756201191646691328` |
| text *sometimes required* | The text of your status update. Required if no `media_keys` are specified. Type: string Example: `just setting up my twttr` |
| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://855591459410511943` |
| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). Type: string Example: `13_1153584529292270722` |
| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false` |
| name *optional* | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` |
#### Example Request
`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01`
#### Example Response
```
{
"request": {
"params": {
"media_keys": [
"3_917438348871983104"
],
"scheduled_at": "2018-01-01T00:00:00Z",
"as_user_id": 756201191646691328
}
},
"data": {
"name": null,
"completed_at": null,
"text": "",
"user_id": "756201191646691328",
"scheduled_status": "SCHEDULED",
"id": "917438609065623552",
"nullcast": true,
"created_at": "2017-10-09T17:16:24Z",
"scheduled_at": "2018-01-01T00:00:00Z",
"card_uri": null,
"updated_at": "2017-10-09T17:16:24Z",
"tweet_id": null,
"media_keys": [
"3_917438348871983104"
]
}
}
```
Update the specified Scheduled Tweet belonging to the current account.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`
#### Parameters
| Name | Description |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` |
| card\_uri *optional* | Associate a card with the Tweet using the `card_uri` value from any cards response, if available. **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://875146925316386347` |
| media\_keys *optional* | Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. **Note**: The media asset must be in the account's [Media Library](https://developer.x.com/en/docs/ads/creatives/api-reference/media-library#media-library). **Note**: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722` |
| nullcast *optional* | Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false` |
| scheduled\_at *optional* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live). Type: string Example: `2017-12-31T23:59:59Z` |
| text *optional* | The text of your status update. Type: string Example: `just setting up my twttr` |
| name *optional* | The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name` |
#### Example Request
`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice`
#### Example Response
```
{
"request": {
"params": {
"scheduled_tweet_id": "875057751231037440",
"text": "winter solstice"
}
},
"data": {
"name": null,
"completed_at": null,
"scheduled_status": "SCHEDULED",
"text": "winter solstice",
"user_id": "756201191646691328",
"id": "875057751231037440",
"nullcast": true,
"created_at": "2017-06-14T18:30:00Z",
"scheduled_at": "2017-12-21T00:00:00Z",
"card_uri": null,
"updated_at": "2017-06-14T18:30:00Z",
"tweet_id": null,
"media_keys": []
}
}
```
Permanently delete the specified Scheduled Tweet belonging to the current account.
**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted Scheduled Tweets.
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`
#### Parameters
| Name | Description |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| scheduled\_tweet\_id *required* | A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177` |
#### Example Request
`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776`
#### Example Response
```
{
"request": {
"params": {
"scheduled_tweet_id": 875064008595787776
}
},
"data": {
"name": null,
"completed_at": null,
"scheduled_status": "DELETED",
"text": "hello, world",
"user_id": "756201191646691328",
"id": "875064008595787776",
"nullcast": true,
"created_at": "2017-06-14T18:54:52Z",
"scheduled_at": "2017-06-15T00:00:00Z",
"card_uri": null,
"updated_at": "2017-06-14T19:01:16Z",
"tweet_id": null,
"media_keys": []
}
}
```
### Tweet Previews
#### GET accounts/:account\_id/tweet\_previews
Preview published, scheduled, or draft Tweets.
* Supports previewing *multiple* Tweets—up to 200—in a single API request
* Accurate, up-to-date rendering of Tweet layout and style
* Supports all the latest formats and card types
* Returns an iframe
#### Resource URL
`https://ads-api.x.com/12/accounts/:account_id/tweet_previews`
#### Parameters
| Name | Description |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| account\_id *required* | The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests excluding [GET accounts](https://developer.x.com/en/docs/ads/campaign-management/api-reference/accounts#get-accounts). The specified account must be associated with the authenticated user. Type: string Example: `18ce54d4x5t` |
| tweet\_ids *required* | A comma-separated list of identifiers. Up to 200 IDs may be provided. **Note**: The IDs should correspond to the specified `tweet_type`. For example, if a Scheduled Tweet ID is passed in and `tweet_type=PUBLISHED` is specified, a preview for that ID will not be returned. Type: long Example: `1122911801354510336,1102836745790316550` |
| tweet\_type *required* | The Tweet type for the specified `tweet_ids`. Type: enum Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED` |
#### Example Request
`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED`
#### Example Response
```
{
"request": {
"params": {
"tweet_ids": [
"1122911801354510336",
"1102836745790316550"
],
"tweet_type": "PUBLISHED",
"account_id": "18ce54d4x5t"
}
},
"data": [
{
"tweet_id": "1122911801354510336",
"preview": "