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

# Creatives API Reference

> Endpoint reference for the X Ads Creatives API covering account media, cards, scheduled Tweets, media library, and promoted video creative operations.

## API Reference

### Account Media

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/account\_media

Retrieve details for some or all account media associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="account_media_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="creative_types" type="enum" 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.<br /><br />
  Possible values: `BANNER`, `BANNER_TABLET`, `INTERSTITIAL`, `INTERSTITIAL_LANDSCAPE`, `INTERSTITIAL_LANDSCAPE_TABLET`, `INTERSTITIAL_TABLET`, `MEDIUM_RECTANGLE`, `PREROLL`, `VAST_PREROLL`
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="account_media_id" type="string" required>
  A reference to the account media you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="account_media_id" type="string" required>
  A reference to the account media you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets), or the [POST accounts/:account\_id/draft\_tweets](/x-ads-api/creatives/reference#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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="card_types" type="enum" optional>
  Scope the response to just the desired card types by specifying a comma-separated list of enum values.<br /><br />
  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`
</ParamField>

<ParamField query="card_id" type="string" 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.
</ParamField>

<ParamField query="card_uris" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="100">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="include_legacy_cards" type="boolean" default="false">
  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.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  The id of the cards.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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](/x-ads-api/creatives/reference#carousels) for a detailed usage example.

**Resource URL[](#resource-url "Permalink to this headline")**

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

**Parameters[](#parameters "Permalink to this headline")**

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.

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="name" type="string" required>
  The name for the card. Maximum length: 80 characters.
</ParamField>

<ParamField query="components" type="array" optional>
  Describes the components to use to create the card. Additional information below. Cannot be specified along with `slides`.<br /><br />
  **Note**: The order of the components is important.
</ParamField>

<ParamField query="slides" type="array" optional>
  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`.<br /><br />
  **Note**: The order of each slide is important.
</ParamField>

#### 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**

<ParamField query="type" type="enum" required>
  The destination type, which determines its schema.<br /><br />
  Possible values: `WEBSITE`
</ParamField>

\| 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` |

<ParamField query="ios_app_store_identifier" type="string" optional>
  The iOS app store identifier.<br /><br />
  **Note**: At least one of following is required: `ios_app_store_identifier` or `googleplay_app_id`.
</ParamField>

<ParamField query="googleplay_deep_link" type="string" optional>
  A deep link into the Android app you're promoting.<br /><br />
  **Note**: Can only be used if an `googleplay_app_id` has been provided.
</ParamField>

<ParamField query="ios_deep_link" type="string" optional>
  A deep link into the iOS app you're promoting.<br /><br />
  **Note**: Can only be used if an `ios_app_store_identifier` has been provided.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264`

**Parameters[](#parameters "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the card. Maximum length: 80 characters.
</ParamField>

<ParamField query="components" type="array" optional>
  Describes the components to use to update the card. Additional information below. Cannot be specified along with `slides`.<br /><br />
  **Note**: The order of the components is important.
</ParamField>

<ParamField query="slides" type="array" 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`.<br /><br />
  **Note**: The order of each slide is important.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  The id of the card to be deleted.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

Retrieve multiple cards, by `card_uri`, associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/all`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="card_uris" type="string" 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.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the card you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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": "/x-ads-api/creatives/reference#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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/draft\_tweets

Retrieve details for some or all Draft Tweets associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="100">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="user_id" type="string" optional>
  Specify the user to retrieve Draft Tweets for. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="draft_tweet_id" type="string" required>
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="as_user_id" type="string" 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.
</ParamField>

<ParamField query="text" type="string" optional>
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField query="card_uri" type="string" optional>
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField query="media_keys" type="string" 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.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField query="nullcast" type="boolean" default="true">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Draft Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="draft_tweet_id" type="string" required>
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

<ParamField query="card_uri" type="string" optional>
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField query="media_keys" type="string" 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.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField query="nullcast" type="boolean" optional>
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField query="text" type="string" optional>
  The text of your status update.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Draft Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="draft_tweet_id" type="string" required>
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="draft_tweet_id" type="string" required>
  A reference to the Draft Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), or [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="card_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the image conversation card you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="first_cta" type="string" required>
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="first_cta_tweet" type="string" required>
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField query="media_key" type="string" required>
  The media key for an image to be used in this card.<br /><br />
  **Note**: The image must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField query="name" type="string" required>
  The name for the card.
</ParamField>

<ParamField query="thank_you_text" type="string" required>
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField query="second_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField query="second_cta_tweet" type="string" optional>
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField query="title" type="string" optional>
  The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField query="third_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="third_cta_tweet" type="string" optional>
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField query="fourth_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="fourth_cta_tweet" type="string" optional>
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField query="unlocked_image_media_key" type="string" 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.<br /><br />
  **Note**: The image must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.
</ParamField>

<ParamField query="thank_you_url" type="string" optional>
  The URL to be displayed with the thank you text.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
{
  "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](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the image conversation card you are operating with in the request.
</ParamField>

<ParamField query="first_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="first_cta_tweet" type="string" optional>
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField query="second_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField query="second_cta_tweet" type="string" optional>
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField query="third_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="third_cta_tweet" type="string" optional>
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField query="fourth_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="fourth_cta_tweet" type="string" optional>
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField query="media_key" type="string" optional>
  The media key for an image to be used in this card.<br /><br />
  **Note**: The image must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the card.
</ParamField>

<ParamField query="thank_you_text" type="string" optional>
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField query="thank_you_url" type="string" optional>
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField query="title" type="string" optional>
  The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField query="unlocked_image_media_key" type="string" 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.<br /><br />
  **Note**: The image must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the image conversation card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/media\_library

Retrieve details for some or all media library objects associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="20">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 50
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="media_type" type="enum" optional>
  Scope the response to just the desired media type.<br /><br />
  Possible values: `GIF`, `IMAGE`, `VIDEO`
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope resource by `name`, `title`, `file_name`, and `description` fields.<br /><br />
  **Note**: This performs case-insensitive *term* matching.<br /><br />
  Min, Max length: `1`, `255`
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="media_key" type="string" required>
  A reference to the media library object you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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](/x-ads-api/creatives/reference#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](/x-ads-api/creatives/reference#get-accounts-account-id-account-media) asset.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="media_key" type="string" 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.
</ParamField>

<ParamField query="description" type="string" optional>
  The description that appears under the video when Tweeted. Maximum length: 200 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField query="file_name" type="string" optional>
  The file name for the media library object. Maximum length: 255.<br /><br />
  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.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the media library object. Maximum length: 100.<br /><br />
  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.
</ParamField>

<ParamField query="poster_media_key" type="string" 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.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField query="title" type="string" optional>
  The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="media_key" type="string" required>
  A reference to the media library object you are operating with in the request.
</ParamField>

<ParamField query="description" type="string" optional>
  The description that appears under the video when Tweeted. Maximum length: 200 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField query="file_name" type="string" optional>
  The file name for the media library object. Maximum length: 255.<br /><br />
  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.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the media library object. Maximum length: 100.<br /><br />
  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.
</ParamField>

<ParamField query="poster_media_key" type="string" optional>
  Specify a poster image for the video using the `media_key` of an uploaded image.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

<ParamField query="title" type="string" optional>
  The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters.<br /><br />
  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](/x-ads-api/creatives/reference#post-accounts-account-id-tweet) endpoint.<br /><br />
  **Note**: Can only be used with videos.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="media_key" type="string" required>
  A reference to the media library object you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/cards/poll

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="card_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the poll card you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="duration_in_minutes" type="int" 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.<br /><br />
  **Note**: This starts as soon as the card is created and not when it is added to a Tweet.<br /><br />
  Min: 5, Max: 10080
</ParamField>

<ParamField query="first_choice" type="string" required>
  The first poll choice. Maximum length: 25 characters.
</ParamField>

<ParamField query="name" type="string" required>
  The name for the card.
</ParamField>

<ParamField query="second_choice" type="string" required>
  The second poll choice. Maximum length: 25 characters.
</ParamField>

<ParamField query="fourth_choice" type="string" optional>
  The fourth poll choice. Maximum length: 25 characters.<br /><br />
  **Note**: The first, second, and third choices must be set when using this parameter.
</ParamField>

<ParamField query="media_key" type="string" 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.<br /><br />
  **Note**: The image or video must be in the account's media library.<br /><br />
  **Note**: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
</ParamField>

<ParamField query="third_choice" type="string" optional>
  The third poll choice. Maximum length: 25 characters.<br /><br />
  **Note**: The first and second choices must be set when using this parameter.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the poll card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="line_item_ids" type="string" 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.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="preroll_call_to_action_ids" type="string" 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.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="preroll_call_to_action_id" type="string" required>
  A reference to the preroll call to action you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="call_to_action" type="enum" required>
  The CTA text for the displayed button within the ad.<br /><br />
  Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField query="call_to_action_url" type="string" required>
  The URL to redirect the user to when the CTA button is clicked.
</ParamField>

<ParamField query="line_item_id" type="string" required>
  A reference to the line item you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="preroll_call_to_action_id" type="string" required>
  A reference to the preroll CTA you are operating with in the request.
</ParamField>

<ParamField query="call_to_action" type="enum" optional>
  The CTA text for the displayed button within the ad.<br /><br />
  Possible values: `GO_TO`, `SEE_MORE`, `SHOP`, `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField query="call_to_action_url" type="string" optional>
  The URL to redirect the user to when the CTA button is clicked.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="preroll_call_to_action_id" type="string" required>
  A reference to the preroll CTA you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/scheduled\_tweets

Retrieve details for some or all Scheduled Tweets associated with the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="count" type="int" default="100">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 200
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="user_id" type="long" optional>
  Specify the user to retrieve Scheduled Tweets for. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="scheduled_tweet_id" type="string" required>
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="scheduled_at" type="string" required>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live).<br /><br />
  **Note**: Tweets can only be scheduled up to one year in the future.<br /><br />
  **Note**: Tweets should only be scheduled at minute-granularity; seconds will be ignored.
</ParamField>

<ParamField query="as_user_id" type="long" 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.
</ParamField>

<ParamField query="text" type="string" optional>
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField query="card_uri" type="string" optional>
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField query="media_keys" type="string" 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.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField query="nullcast" type="boolean" default="true">
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Scheduled Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`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[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="scheduled_tweet_id" type="string" required>
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

<ParamField query="card_uri" type="string" optional>
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField query="media_keys" type="string" 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.<br /><br />
  **Note**: The media asset must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: Unset (remove) by specifying the parameter without a value.
</ParamField>

<ParamField query="nullcast" type="boolean" optional>
  Whether to create a nullcasted (or "Promoted-only") Tweet.
</ParamField>

<ParamField query="scheduled_at" type="string" optional>
  The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the Tweet should be published (or go live).
</ParamField>

<ParamField query="text" type="string" optional>
  The text of your status update.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Scheduled Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice`

**Example Response[](#example-response "Permalink to this headline")**

```
{
  "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[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="scheduled_tweet_id" type="string" required>
  A reference to the Scheduled Tweet you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776`

**Example Response[](#example-response "Permalink to this headline")**

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

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### 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[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="tweet_ids" type="string" required>
  A comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />
  **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.
</ParamField>

<ParamField query="tweet_type" type="enum" required>
  The Tweet type for the specified `tweet_ids`.<br /><br />
  Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED`

**Example Response[](#example-response "Permalink to this headline")**

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

### Tweets

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

#### GET accounts/:account\_id/tweets

Retrieve Tweet details for the account's full promotable user (default) or the user specified in the `user_id` parameter. This can be any of the [promotable users](/x-ads-api/campaign-management/reference) under the account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="tweet_type" type="enum" required>
  The Tweet type for the specified `tweet_ids`.<br /><br />
  Possible values: `DRAFT`, `PUBLISHED`, `SCHEDULED`
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="include_mentions_and_replies" type="boolean" default="false">
  Whether to filter out mentions and replies from the list of available Tweets.
</ParamField>

<ParamField query="name" type="string" optional>
  An optional query to scope Tweets by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField query="timeline_type" type="enum" default="NULLCAST">
  Whether to return nullcasted (a.k.a. "Promoted-only") Tweets, organic Tweets, or both.<br /><br />
  Possible values: `ALL`, `NULLCAST`, `ORGANIC`
</ParamField>

<ParamField query="trim_user" type="boolean" default="false">
  Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet's author's user ID.
</ParamField>

<ParamField query="tweet_ids" type="string" optional>
  A comma-separated list of identifiers. Up to 200 IDs may be provided.<br /><br />
  **Note**: The IDs should correspond to the specified `tweet_type`. For example, if a Scheduled Tweet ID is passed in, then the `tweet_type` **must** be `SCHEDULED` in order for that Tweet to be returned in the response.
</ParamField>

<ParamField query="user_id" type="long" optional>
  Specifies the user to scope Tweets to. Defaults to the `FULL` promotable user on the account when not set.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true`

**Example Response[](#example-response "Permalink to this headline")**

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

#### POST accounts/:account\_id/tweet

Create a Tweet for the account's full promotable user (default) or the user specified in the `as_user_id` parameter. Both nullcasted (default) and organic Tweet creation is supported. Nullcasted Tweets do not appear in the public timeline and are not served to followers. Either type can be used in campaigns.

If the authenticated user is not the `FULL` promotable user on this account, determine if they have permission to Tweet on behalf this user by making a request to the [GET accounts/:account\_id/authenticated\_user\_access](/x-ads-api/campaign-management/reference) endpoint. A permission of `TWEET_COMPOSER` indicates that the user may use this endpoint to create nullcasted Tweets on behalf of the `FULL` [promotable user](/x-ads-api/campaign-management/reference#get-accounts-account-id-promotable-users).

When using the [upload.x.com endpoint](/x-api/media/initialize-media-upload) for media, pass in the same `user_id` value for the `additional_owners` parameter as the `as_user_id` value that you pass in to this endpoint.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="as_user_id" type="long" 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.
</ParamField>

<ParamField query="text" type="string" optional>
  The text of your status update. Required if no `media_keys` are specified.
</ParamField>

<ParamField query="card_uri" type="string" optional>
  Associate a card with the Tweet using the `card_uri` value from any cards response, if available.
</ParamField>

<ParamField query="conversation_settings" type="enum" default="EVERYONE">
  Choose who can reply to this Tweet. Anyone mentioned can always reply.<br /><br />
  **Note**: This field will *not* be returned in the POST request response, but will be returned when making a GET request.<br /><br />
  **Note**: This parameter only works in Ads API v8 and above.<br /><br />
  Possible values: `EVERYONE`, `FOLLOWING`, `MENTIONED_USERS`
</ParamField>

<ParamField query="media_keys" type="string" 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.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Tweet. Maximum length: 80 characters.
</ParamField>

<ParamField query="nullcast" type="boolean" default="true">
  Whether to create a nullcasted (or "Promoted-only") Tweet.<br /><br />
  **Note**: Organic Tweets (`nullcast=false`) can only be created for the authenticated user.
</ParamField>

<ParamField query="trim_user" type="boolean" default="false">
  Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet's author's user ID.
</ParamField>

<ParamField query="tweet_mode" type="string" optional>
  Whether the response should be in compatibility or extended mode. See [this](/x-api/fundamentals/post-annotations) for additional information.<br /><br />
  Possible values: `compat`, `extended`
</ParamField>

<ParamField query="video_cta" type="enum" optional>
  The CTA for the video.<br /><br />
  Possible values: `VISIT_SITE`, `WATCH_NOW`
</ParamField>

<ParamField query="video_cta_value" type="string" optional>
  The value for the corresponding CTA on the video.
</ParamField>

<ParamField query="video_description" type="string" optional>
  The description that appears under the video. Maximum length: 200 characters.
</ParamField>

<ParamField query="video_title" type="string" optional>
  The title (headline) that appears under the video. Maximum length: 70 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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

Update the specified Tweet `name` belonging to the current account.

**Resource URL[](#resource-url "Permalink to this headline")**

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

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="tweet_id" type="long" required>
  A reference to the Tweet you are operating with in the request.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the Tweet. Maximum length: 80 characters.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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

### Video Conversation Cards

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Run in Postman
</Button>

**Note**: To associate a card with a Tweet, use the `card_uri` parameter with either the [POST accounts/:account\_id/tweet](/x-ads-api/creatives/reference#post-accounts-account-id-tweet), [POST statuses/update](/x-api/posts/create-post), or [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives/reference#post-accounts-account-id-scheduled-tweets) endpoints.

#### GET accounts/:account\_id/cards/video\_conversation

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="card_ids" type="string" optional>
  Scope the response to just the desired video conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
</ParamField>

<ParamField query="count" type="int" default="200">
  Specifies the number of records to try and retrieve per distinct request.<br />
  Min: 1, Max: 1000
</ParamField>

<ParamField query="cursor" type="string" optional>
  Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/fundamentals/pagination) for more information.
</ParamField>

<ParamField query="q" type="string" optional>
  An optional query to scope cards by `name`. Omit this parameter to retrieve all. Maximum length: 80 characters.<br /><br />
  **Note**: This performs case-insensitive prefix matching.
</ParamField>

<ParamField query="sort_by" type="string" optional>
  Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

<ParamField query="with_total_count" type="boolean" default="false">
  Include the `total_count` response attribute.<br /><br />
  **Note**: This parameter and `cursor` are exclusive. Requests which include `total_count` will have lower rate limits (currently 200 per 15 minutes).
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h`

**Example Response[](#example-response "Permalink to this headline")**

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

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

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the video conversation card you are operating with in the request.
</ParamField>

<ParamField query="with_deleted" type="boolean" default="false">
  Include deleted results in your request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

`GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h`

**Example Response[](#example-response "Permalink to this headline")**

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

#### POST accounts/:account\_id/cards/video\_conversation

Create a new video conversation card associated with the specified account.

See [Uploading Media](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField query="first_cta" type="string" required>
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="first_cta_tweet" type="string" required>
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField query="media_key" type="string" required>
  The media key for a video to be used in this card.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: An aspect ratio of 16:9 is required.
</ParamField>

<ParamField query="name" type="string" required>
  The name for the card.
</ParamField>

<ParamField query="thank_you_text" type="string" required>
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField query="title" type="string" optional>
  The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField query="second_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField query="second_cta_tweet" type="string" optional>
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField query="poster_media_key" type="long" optional>
  The media key for a poster image to be used in this card. If not specified, the first frame will be used.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField query="third_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="third_cta_tweet" type="string" optional>
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField query="fourth_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="fourth_cta_tweet" type="string" optional>
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField query="thank_you_url" type="string" optional>
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField query="unlocked_image_media_key" type="string" 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.<br /><br />
  **Note**: The image must be in the account's media library.
</ParamField>

<ParamField query="unlocked_video_media_key" type="string" optional>
  The identifier of a video from the [GET accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) endpoint which will be used in the instant unlock scenario.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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

Update the specified video conversation card belonging to the current account.

See [Uploading Media](/x-api/media/quickstart/media-upload-chunked) for useful information on uploading images to our endpoints.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the video conversation card you are operating with in the request.
</ParamField>

<ParamField query="first_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="first_cta_tweet" type="string" optional>
  The Tweet text to be used when the first CTA is clicked.
</ParamField>

<ParamField query="second_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #).<br /><br />
  **Note**: Required if `title` is `not` set.
</ParamField>

<ParamField query="second_cta_tweet" type="string" optional>
  The Tweet text to be used when the second CTA is clicked.<br /><br />
  **Note**: Required if `second_cta` is set.
</ParamField>

<ParamField query="third_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="third_cta_tweet" type="string" optional>
  The Tweet text to be used when the third CTA is clicked.<br /><br />
  **Note**: Required if `third_cta` is set.
</ParamField>

<ParamField query="fourth_cta" type="string" optional>
  The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #).
</ParamField>

<ParamField query="fourth_cta_tweet" type="string" optional>
  The Tweet text to be used when the fourth CTA is clicked.<br /><br />
  **Note**: Required if `fourth_cta` is set.
</ParamField>

<ParamField query="media_key" type="string" optional>
  The media key for a video to be used in this card.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).<br /><br />
  **Note**: An aspect ratio of 16:9 is required.
</ParamField>

<ParamField query="name" type="string" optional>
  The name for the card.
</ParamField>

<ParamField query="poster_media_key" type="long" optional>
  The media key for a poster image to be used in this card. If not specified, the first frame will be used.<br /><br />
  **Note**: The video must be in the account's [Media Library](/x-ads-api/creatives/reference#media-library).
</ParamField>

<ParamField query="thank_you_text" type="string" optional>
  The text to be displayed after the CTA is clicked. Maximum length: 23 characters.
</ParamField>

<ParamField query="thank_you_url" type="string" optional>
  The URL to be displayed with the thank you text.
</ParamField>

<ParamField query="title" type="string" optional>
  The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters.<br /><br />
  **Note**: Required if `second_cta` is `not` set.
</ParamField>

<ParamField query="unlocked_image_media_key" type="string" 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.<br /><br />
  **Note**: The image must be in the account's media library.
</ParamField>

<ParamField query="unlocked_video_media_key" type="string" optional>
  The identifier of a video from the [GET accounts/:account\_id/media\_library](/x-ads-api/creatives/reference#media-library) endpoint which will be used in the instant unlock scenario.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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

Permanently delete the specified video conversation card belonging to the current account.

**Note**: This is a hard delete. As a result, it is not possible to retrieve deleted cards.

**Resource URL[](#resource-url "Permalink to this headline")**

`https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id`

<ParamField path="account_id" type="string" required>
  The identifier for the leveraged account. Appears within the resource's path and is generally a required parameter for all Advertiser API requests. The specified account must be associated with the authenticated user.
</ParamField>

<ParamField path="card_id" type="string" required>
  A reference to the video conversation card you are operating with in the request.
</ParamField>

**Example Request[](#example-request "Permalink to this headline")**

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

**Example Response[](#example-response "Permalink to this headline")**

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