Creatives API Reference

Complete technical reference for all Creatives endpoints in the X Ads API — Cards, Tweets, Media Library, Account Media, Draft Tweets, Polls, Preroll CTAs, Conversation Cards, Scheduled Tweets, and more.

API Reference

Account Media

GET accounts/:account_id/account_media

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
account_media_ids optional	Scope the response to just the desired account media by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 3wpx
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
creative_types optional	Scope the response to just the account media that match the specified creative types. More than one creative type may be specified by comma-separating enum values. Type: enum Possible values: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

Retrieve a specific account media object associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
account_media_id required	A reference to the account media you are operating with in the request. Type: string Example: 2pnfd
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

Delete the specified account media object belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
account_media_id required	A reference to the account media you are operating with in the request. Type: string Example: 2pnfd

Example Request

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

Example Response

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}

Cards

Note: To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, POST accounts/:account_id/scheduled_tweets, or the POST accounts/:account_id/draft_tweets endpoints.

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

Note: This only returns cards that were created using the POST accounts/:account_id/cards endpoint. Cards created using other endpoints are not returned.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_types optional	Scope the response to just the desired card types by specifying a comma-separated list of enum values. Type: enum Possible values: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE, VIDEO_WEBSITE
card_id optional	Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card IDs may be provided. Type: string Example: 1044294149527166979,1044301099031658496
card_uris optional	Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: card://1044294149527166979,card://1044301099031658496
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 100 Min, Max: 1, 200
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
include_legacy_cards optional	Include legacy website and app cards in the response. Legacy cards are those whose resource URL has the following format: accounts/:account_id/cards/:card_type. See this developer forum post for additional context. Type: boolean Default: false Possible values: true, false
q optional	An optional query to scope cards by name. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: dtc
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Retrieve details for a single card associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	The id of the cards. Type: string Example: 1044294149527166979
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

POST accounts/:account_id/cards

Create a new card associated to the specified account.

Card create requests only accept JSON POST bodies. The Content-Type must be set to application/json.

See our Carousels Guide for a detailed usage example.

Resource URL

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

Parameters

The JSON POST body must include a card name and an array of components. Components are represented as objects and describe the advertiser-facing attributes of the card.

The following example shows the general structure of the payload (but includes non-working information).

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

Additional information on components below.

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
name required	The name for the card. Maximum length: 80 characters. Type: string Example: component based card
components sometimes required	Describes the components to use to create the card. Additional information below. Cannot be specified along with slides. Note: The order of the components is important. Type: array of objects
slides sometimes required	Use this array of array to create Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with components. Note: The order of each slide is important. Type: array of array

Components

Every component must include a type field which determines the object’s schema. The Ads API supports the following component types, grouped into media- and description-based components.

• Media:
• MEDIA: single video or image
• SWIPEABLE_MEDIA: between 2-6 videos or images
• Description:
• DETAILS
• BUTTON

Each component has a set of required fields (in addition to the type key). These are listed in the following table.

Component type	Field	Value type
MEDIA	media_key	string
SWIPEABLE_MEDIA	media_keys	array of strings
DETAILS	title destination	string object
BUTTON	label destination	object object

The following is an example of a BUTTON component in the context of the components array (intentionally omitting the name key). (The ellipses indicate places where more information would need to be specified.)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

The order in which the component objects are specified defines the top-to-bottom order in which they will be rendered. Cards must be created using one media-based component and either a DETAILS or BUTTON component. Description-based components are rendered under media and have associated destinations, either URLs or mobile apps.

Label

Labels define the text shown on buttons and, therefore, only apply to the BUTTON component. Label objects have two required keys: type and value. The type must be set to ENUM and the value can be one of: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY, or SHOP.

Building on the previous example, the following shows the label object within the BUTTON component.

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

Destination

Destinations are where advertisers intend to take users. They are always required within DETAILS or BUTTON components. There are two destination types: WEBSITE or APP.

Note: Website destinations can only be used with DETAILS components and app destinations can only be used with BUTTON components.

Website Destination

Name	Description
type required	The destination type, which determines its schema. Type: enum Possible values: WEBSITE
url required	The URL of the website to redirect a user to. Type: string Example: https://devcommunity.x.com/c/advertiser-api

App Destination

Name	Description
type required	The destination type, which determines its schema. Type: enum Possible values: APP
country_code required	The ISO 3166-1 alpha-2 two-letter code for the country where the app is sold. Type: string Example: US
googleplay_app_id sometimes required	The Google Play application package name. Note: At least one of following is required: ios_app_store_identifier or googleplay_app_id. Type: string Example: com.twitter.android
ios_app_store_identifier sometimes required	The iOS app store identifier. Note: At least one of following is required: ios_app_store_identifier or googleplay_app_id. Type: string Example: 333903271
googleplay_deep_link optional	A deep link into the Android app you’re promoting. Note: Can only be used if an googleplay_app_id has been provided. Type: string
ios_deep_link optional	A deep link into the iOS app you’re promoting. Note: Can only be used if an ios_app_store_identifier has been provided. Type: string

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "components create cards",
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON",
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US",
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false,
    "card_type": "IMAGE_APP"
  }
}

Update the specified associated with the current account.

Card edit requests only accept JSON POST bodies. The Content-Type must be set to application/json.

Resource URL

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

Parameters

The JSON POST body must include the parameters that will be updated. The request will replace each field with the parameters specified within the payload. Components are represented as objects and describe the advertiser-facing attributes of the card.

The following example shows the general structure of the payload (but includes non-working information).

{
  "name": "some name",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "value"
    }
  ]
}

Additional information on components and slides in POST accounts/:account_id/cards.

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
name optional	The name for the card. Maximum length: 80 characters. Type: string Example: component based card
components optional	Describes the components to use to update the card. Additional information below. Cannot be specified along with slides. Note: The order of the components is important. Type: array of objects
slides optional	Use this array of array to update Multi-Destination Carousels. Describes each card as a grouping of components. Each slide should be a complete representation of a card. Cannot be specified along with components. Note: The order of each slide is important. Type: array of array

Example Request

This example updates both the name and removes one of the media_keys from the components field from the example above.

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

{
  "name": "changed name",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "3_1075096386931052545"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "OPEN"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
      }
    }
  ]
}

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "changed name",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Delete the specified card belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	The id of the card to be deleted. Type: string Example: 1044294149527166979

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Cards Fetch

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_uris required	Scope the response to just the desired cards by specifying a comma-separated list of identifiers. Up to 200 card URI values may be provided. Type: string Example: card://1044294149527166979,card://1044301099031658496
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_uris": [
        "card://1044294149527166979",
        "card://1044301099031658496"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "name": "X App",
      "googleplay_app_id": "com.twitter.android",
      "image_display_height": "836",
      "country_code": "US",
      "id": "692xn",
      "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg",
      "created_at": "2018-09-24T18:35:01Z",
      "image_display_width": "1600",
      "card_uri": "card://1044294149527166979",
      "updated_at": "2018-09-24T18:35:01Z",
      "app_cta": "INSTALL",
      "deleted": false,
      "card_type": "IMAGE_APP_DOWNLOAD"
    },
    {
      "video_poster_height": "9",
      "name": "Developer Platform",
      "website_shortened_url": "https://t.co/zadeUSVD18",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap",
      "content_duration_seconds": "24",
      "video_owner_id": "756201191646691328",
      "video_content_id": "13_991374284135137280",
      "website_display_url": "developer.x.com",
      "id": "6933h",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2",
      "website_dest_url": "https://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Developer Platform",
      "website_url": "https://developer.x.com",
      "updated_at": "2018-09-24T19:02:38Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_WEBSITE"
    }
  ]
}

Retrieve a specific card, by card_id, associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the card you are operating with in the request. Type: string Example: 508pf
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_id": "508pf",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "video website card",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap",
    "content_duration_seconds": "21",
    "video_owner_id": "756201191646691328",
    "video_content_id": "13_867520357225418752",
    "website_display_url": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website",
    "created_at": "2017-11-10T09:00:35Z",
    "card_uri": "card://928910245920829440",
    "title": "VWC",
    "website_url": "https://t.co/F81hp59pUF",
    "updated_at": "2018-01-05T05:43:31Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_WEBSITE"
  }
}

Draft Tweets

GET accounts/:account_id/draft_tweets

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 100 Min, Max: 1, 200
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: c-jh1g0ryb
user_id optional	Specify the user to retrieve Draft Tweets for. Defaults to the FULL promotable user on the account when not set. Type: string Example: 756201191646691328

Example Request

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

Example Response

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name" null,
      "text": "hello, world",
      "user_id": "756201191646691328",
      "id": "994791681219231744",
      "nullcast": true,
      "created_at": "2018-05-11T04:09:53Z",
      "card_uri": null,
      "updated_at": "2018-05-11T04:09:53Z",
      "media_keys": []
    }
  ],
  "next_cursor": "c-jh1g0ryb"
}

Retrieve a specific Draft Tweet associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
draft_tweet_id required	A reference to the Draft Tweet you are operating with in the request. Type: string Example: 994788364334325760

Example Request

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

Example Response

{
  "request": {
    "params": {
      "draft_tweet_id": "994788364334325760"
    }
  },
  "data": {
    "name": null,
    "text": "#TwitterDev",
    "user_id": "756201191646691328",
    "id": "994788364334325760",
    "nullcast": true,
    "created_at": "2018-05-11T03:56:42Z",
    "card_uri": "card://958225772740714496",
    "updated_at": "2018-05-11T03:56:42Z",
    "media_keys": []
  }
}

POST accounts/:account_id/draft_tweets

Create a Draft Tweet for the account’s full promotable user (default) or the user specified in the as_user_id parameter.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
as_user_id required	The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via ads.x.com. This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser’s. Type: string Example: 756201191646691328
text sometimes required	The text of your status update. Required if no media_keys are specified. Type: string Example: Just setting up my X.
card_uri optional	Associate a card with the Tweet using the card_uri value from any cards response, if available. Type: string Example: card://960880280705392541
media_keys optional	Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. Note: The media asset must be in the account’s Media Library. Type: string Example: 13_1153584529292270722
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Type: boolean Default: true Possible values: true, false
name optional	The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name

Example Request

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

Example Response

{
  "request": {
    "params": {
      "text": "Just setting up my X.",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "Just setting up my X.",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

Update the specified Draft Tweet belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
draft_tweet_id required	A reference to the Draft Tweet you are operating with in the request. Type: string Example: 994747471329873920
card_uri optional	Associate a card with the Tweet using the card_uri value from any cards response, if available. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: card://970582057284129151
media_keys optional	Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. Note: The media asset must be in the account’s Media Library. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: 13_1153584529292270722
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Type: boolean Possible values: true, false
text optional	The text of your status update. Type: string Example: just setting up my twttr
name optional	The name for the Draft Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name

Example Request

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

Example Response

{
  "request": {
    "params": {
      "draft_tweet_id": 994747471329873920,
      "text": "just setting up my twttr"
    }
  },
  "data": {
    "name": null,
    "text": "just setting up my twttr",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

Permanently delete the specified Draft Tweet belonging to the current account.

Note: We strongly recommend deleting drafts once a Tweet or Scheduled Tweet has been created using its metadata.

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
draft_tweet_id required	A reference to the Draft Tweet you are operating with in the request. Type: string Example: 994787835663155200

Example Request

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

Example Response

{
  "request": {
    "params": {
      "draft_tweet_id": "994787835663155200"
    }
  },
  "data": {
    "name": null,
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "994787835663155200",
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-11T03:54:36Z",
    "card_uri": null,
    "updated_at": "2018-05-11T04:07:31Z",
    "media_keys": []
  }
}

POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id

Preview a Draft Tweet on a mobile device.

A successful request sends a notification to every device the authenticated user is logged in to. Clicking on the notification opens a timeline that allows the user to see and interact with the Draft Tweet, enabling them to test auto-play, volume, fullscreen, video website card docking, and other behaviors.

Note: On-device previews are only visible to the user who receives the notification.

Note: Notifications only get sent to X official apps.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
draft_tweet_id required	A reference to the Draft Tweet you are operating with in the request. Type: string Example: 996132315829948416

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "See @apimctestface's notifications in the X app to preview your Tweet."
}

Image Conversation Cards

Note: To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, or POST accounts/:account_id/scheduled_tweets endpoints.

GET accounts/:account_id/cards/image_conversation

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_ids optional	Scope the response to just the desired image conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 59woh
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope cards by name. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: night
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "id": "59woh",
      "first_cta_tweet": "stars",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "Full moon",
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the image conversation card you are operating with in the request. Type: string Example: 59woh
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

POST accounts/:account_id/cards/image_conversation

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

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
first_cta required	The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareNow
first_cta_tweet required	The Tweet text to be used when the first CTA is clicked. Type: string Example: I Heart @AdsAPI
media_key required	The media key for an image to be used in this card. Note: The image must be in the account’s Media Library. Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: 3_1151345051104991073
name required	The name for the card. Type: string Example: image conversation card
thank_you_text required	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: Thank you
second_cta sometimes required	The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string Note: Required if title is not set. Example: #ShareAgain
second_cta_tweet sometimes required	The Tweet text to be used when the second CTA is clicked. Note: Required if second_cta is set. Type: string Example: I Heart @AdsAPI Again
title sometimes required	The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if second_cta is not set. Example: Start a conversation
third_cta optional	The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareMore
third_cta_tweet sometimes required	The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if third_cta is set. Example: I Heart @TwitterDev
fourth_cta optional	The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareExtra
fourth_cta_tweet sometimes required	The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if fourth_cta is set. Example: I Heart @TwitterDev Again
unlocked_image_media_key optional	A media_key of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. Note: The image must be in the account’s media library. Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: 3_883112887618682880
thank_you_url optional	The URL to be displayed with the thank you text. Type: string Example: https://example.com/thankyou

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon

Example Response

{
  "data": {
    "name": "image conversation card",
    "first_cta": "#moon",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "thanks",
    "id": "59woh",
    "first_cta_tweet": "stars",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Full moon",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "image conversation card",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "thanks",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "stars",
      "image_display_width": "1280",
      "title": "Full moon",
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

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

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the image conversation card you are operating with in the request. Type: string Example: 4i0qg
first_cta optional	The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareNow
first_cta_tweet optional	The Tweet text to be used when the first CTA is clicked. Type: string Example: I Heart @AdsAPI
second_cta optional	The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string Note: Required if title is not set. Example: #ShareAgain
second_cta_tweet optional	The Tweet text to be used when the second CTA is clicked. Note: Required if second_cta is set. Type: string Example: I Heart @AdsAPI Again
third_cta optional	The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareMore
third_cta_tweet optional	The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if third_cta is set. Example: I Heart @TwitterDev
fourth_cta optional	The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareExtra
fourth_cta_tweet optional	The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if fourth_cta is set. Example: I Heart @TwitterDev Again
media_key optional	The media key for an image to be used in this card. Note: The image must be in the account’s Media Library. Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required. Type: string Example: 3_1151345051104991073
name optional	The name for the card. Type: string Example: moon card
thank_you_text optional	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: Thank you
thank_you_url optional	The URL to be displayed with the thank you text. Type: string Example: https://example.com/thankyou
title optional	The title for the card, which appears below the image and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if second_cta is not set. Example: Start a conversation
unlocked_image_media_key optional	A media_key of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. Note: The image must be in the account’s media library. Note: A minimum image width of 800px and a width:height aspect ratio of 5:2 is required. Type: string Example: 3_883112887618682880

Example Request

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

Example Response

{
  "data": {
    "name": "moon card",
    "id": "59woh",
    "created_at": "2018-01-27T04:58:42Z",
    "card_uri": "card://923498485702009837",
    "updated_at": "2018-01-29T21:04:39Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_CONVERSATION",
      "card_id": "59woh",
      "name": "moon card"
    }
  }
}

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

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the image conversation card you are operating with in the request. Type: string Example: 4i0qe

Example Request

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

Example Response

{
  "data": {
    "name": "image conversation card",
    "id": "4i0qe",
    "created_at": "2017-07-07T00:03:01Z",
    "updated_at": "2017-08-23T13:26:23Z",
    "deleted": true,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0qe",
      "card_type": "image_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}

Media Library

GET accounts/:account_id/media_library

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 20 Min, Max: 1, 50
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: c-1
media_type optional	Scope the response to just the desired media type. Type: enum Possible values: GIF, IMAGE, VIDEO
q optional	An optional query to scope resource by name, title, file_name, and description fields. Note: This performs case-insensitive term matching. Type: string Min, Max length: 1, 255

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

Retrieve a specific media library object associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_key required	A reference to the media library object you are operating with in the request. Type: string Example: 13_909110614026444802

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "buildings",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

Associate a media object with the current account. For additional details, please see our Media Library guide.

Note: When adding a video with the AMPLIFY_VIDEO media category to the Media Library, it is automatically available as a PREROLL account_media asset.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_key required	The media_key for the uploaded content. A media_key is returned in the POST media/upload response when a media_category is specified. Type: string Example: 3_931236738554519552
description optional	The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video’s description, use the video_description parameter with the POST accounts/:account_id/tweet endpoint. Note: Can only be used with videos. Type: string Example: This is the description under the video.
file_name optional	The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the file_name is not set. Type: string Example: coffee.jpeg
name optional	The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be “Untitled” when the name is not set. Type: string Example: Latte
poster_media_key optional	Specify a poster image for the video using the media_key of an uploaded image. If not specified, the first frame will be used. Note: Can only be used with videos. Type: string Example: 3_890599134483242005
title optional	The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video’s title, use the video_title parameter with the POST accounts/:account_id/tweet endpoint. Note: Can only be used with videos. Type: string Example: Video title

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

Update the specified media library object belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_key required	A reference to the media library object you are operating with in the request. Type: string Example: 16_844800354743074820
description optional	The description that appears under the video when Tweeted. Maximum length: 200 characters. This is not rendered in the Tweet by default. To display the video’s description, use the video_description parameter with the POST accounts/:account_id/tweet endpoint. Note: Can only be used with videos. Type: string Example: This is the description under the video.
file_name optional	The file name for the media library object. Maximum length: 255. The file name can be seen in the media detail of every media asset in the Media Library UI on ads.x.com. This will be empty when the file_name is not set. Type: string Example: coffee.jpeg
name optional	The name for the media library object. Maximum length: 100. This is the label under every media asset in the Media Library UI on ads.x.com. The label will be “Untitled” when the name is not set. Type: string Example: Latte
poster_media_key optional	Specify a poster image for the video using the media_key of an uploaded image. Note: Can only be used with videos. Type: string Example: 3_885003359340375465
title optional	The title (headline) that appears under the video when Tweeted. Maximum length: 70 characters. This is not rendered in the Tweet by default. To display the video’s title, use the video_title parameter with the POST accounts/:account_id/tweet endpoint. Note: Can only be used with videos. Type: string Example: Video title

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "cat GIF",
      "description": "in space"
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "in space",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "cat GIF",
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

Delete the specified media library object belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
media_key required	A reference to the media library object you are operating with in the request. Type: string Example: 7_860318603387600896

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "uploaded on ads.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

Poll Cards

GET accounts/:account_id/cards/poll

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_ids optional	Scope the response to just the desired poll cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 57i77
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope cards by name. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: night
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "best coast poll",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "East",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "West",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

Retrieve a specific poll card associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the poll card you are operating with in the request. Type: string Example: 57i8t
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "text only poll",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Morning",
    "second_choice": "Evening",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

POST accounts/:account_id/cards/poll

Create a new poll card associated with the specified account. This endpoint supports creating poll cards with either an image, a video, or no media. Polls with media are referred to as Media Forward Polls.

Note: The Media Forward Polls product is in beta and requires the PROMOTED_MEDIA_POLLS account feature.

Note: It is not possible to update (PUT) poll cards.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
duration_in_minutes required	The amount of time (in minutes) the poll will remain open. After the specified duration_in_minutes, the poll will close and votes will no longer be accepted. This corresponds to end_time in the response. Note: This starts as soon as the card is created and not when it is added to a Tweet. Type: int Min, Max: 5, 10080
first_choice required	The first poll choice. Maximum length: 25 characters. Type: string Example: One
name required	The name for the card. Type: string Example: poll card
second_choice required	The second poll choice.Maximum length: 25 characters. Type: string Example: Two
fourth_choice optional	The fourth poll choice. Maximum length: 25 characters. Note: The first, second, and third choices must be set when using this parameter. Type: string Example: Four
media_key optional	The media_key of a media library image or video which will be used in this card. This is a write-only field. In the response, the API will provide a X URL for this media. Note: The image or video must be in the account’s media library. Note: A minimum image width of 800px and a width:height aspect ratio of 1.91:1 is required.
third_choice optional	The third poll choice. Maximum length: 25 characters. Note: The first and second choices must be set when using this parameter. Type: string Example: Three

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll

Example Response

{
  "request": {
    "params": {
      "first_choice": "East",
      "name": "best coast poll",
      "second_choice": "West",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "best coast poll",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "East",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "West",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

Permanently delete the specified poll card belonging to the current account.

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the poll card you are operating with in the request. Type: string Example: 57i9t

Example Request

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

Example Response

{
  "data": {
    "name": "poll with image",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll",
      "account_id": "18ce54d4x5t"
    }
  }
}

Preroll Call To Actions

GET accounts/:account_id/preroll_call_to_actions

Retrieve details for some or all preroll Call-To-Actions (CTAs) associated with line items under the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
line_item_ids optional	Scope the response to just the preroll CTAs associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8v53k
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
preroll_call_to_action_ids optional	Scope the response to just the desired preroll CTAs by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 8f0
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.x.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

Retrieve a specific Call-to-Action (CTAs) associated with this account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	A reference to the preroll call to action you are operating with in the request. Type: string Example: 8f0
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

POST accounts/:account_id/preroll_call_to_actions

Set the optional Call-to-Action (CTA) for a PREROLL_VIEWS line item.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
call_to_action required	The CTA text for the displayed button within the ad. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url required	The URL to redirect the user to when the CTA button is clicked. Type: string Example: https://www.x.com
line_item_id required	A reference to the line item you are operating with in the request. Type: string Example: 8v53k

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.x.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

Update the optional Call-to-Action (CTA) for a PREROLL_VIEWS line item.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	A reference to the preroll CTA you are operating with in the request. Type: string Example: 8f0
call_to_action optional	The CTA text for the displayed button within the ad. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url optional	The URL to redirect the user to when the CTA button is clicked. Type: string Example: https://www.x.com

Example Request

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

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

Delete the specified preroll Call-to-Action (CTA) belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id required	A reference to the preroll CTA you are operating with in the request. Type: string Example: 8f0

Example Request

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

Example Response

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}

Scheduled Tweets

GET accounts/:account_id/scheduled_tweets

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 100 Min, Max: 1, 200
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: c-j3cn6n40
user_id optional	Specify the user to retrieve Scheduled Tweets for. Defaults to the FULL promotable user on the account when not set. Type: long Example: 756201191646691328

Example Request

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

Example Response

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "test name",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "where you want to be",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

Retrieve a specific Scheduled Tweet associated with the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: 917438609065623552

Example Request

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

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

POST accounts/:account_id/scheduled_tweets

Create a Scheduled Tweet for the account’s full promotable user (default) or the user specified in the as_user_id parameter.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_at required	The time, expressed in ISO 8601, that the Tweet should be published (or go live). Note: Tweets can only be scheduled up to one year in the future. Note: Tweets should only be scheduled at minute-granularity; seconds will be ignored. Type: string Example: 2017-12-31T23:59:00Z
as_user_id required	The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via ads.x.com. This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser’s. Type: long Example: 756201191646691328
text sometimes required	The text of your status update. Required if no media_keys are specified. Type: string Example: just setting up my twttr
card_uri optional	Associate a card with the Tweet using the card_uri value from any cards response, if available. Type: string Example: card://855591459410511943
media_keys optional	Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. Note: The media asset must be in the account’s Media Library. Type: string Example: 13_1153584529292270722
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Type: boolean Default: true Possible values: true, false
name optional	The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01

Example Response

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

Update the specified Scheduled Tweet belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: 870321875435442177
card_uri optional	Associate a card with the Tweet using the card_uri value from any cards response, if available. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: card://875146925316386347
media_keys optional	Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. Note: The media asset must be in the account’s Media Library. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: 13_1153584529292270722
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Type: boolean Possible values: true, false
scheduled_at optional	The time, expressed in ISO 8601, that the Tweet should be published (or go live). Type: string Example: 2017-12-31T23:59:59Z
text optional	The text of your status update. Type: string Example: just setting up my twttr
name optional	The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name

Example Request

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

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "winter solstice"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "winter solstice",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Permanently delete the specified Scheduled Tweet belonging to the current account.

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
scheduled_tweet_id required	A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: 870321875435442177

Example Request

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

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Tweet Previews

GET accounts/:account_id/tweet_previews

Preview published, scheduled, or draft Tweets.

• Supports previewing multiple Tweets—up to 200—in a single API request
• Accurate, up-to-date rendering of Tweet layout and style
• Supports all the latest formats and card types
• Returns an iframe

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tweet_ids required	A comma-separated list of identifiers. Up to 200 IDs may be provided. Note: The IDs should correspond to the specified tweet_type. For example, if a Scheduled Tweet ID is passed in and tweet_type=PUBLISHED is specified, a preview for that ID will not be returned. Type: long Example: 1122911801354510336,1102836745790316550
tweet_type required	The Tweet type for the specified tweet_ids. Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED

Example Request

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

Example Response

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

Tweets

GET accounts/:account_id/tweets

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tweet_type required	The Tweet type for the specified tweet_ids. Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: AAAAAFhLRpQLNF-sGBSgAA
include_mentions_and_replies optional	Whether to filter out mentions and replies from the list of available Tweets. Type: boolean Default: false Possible values: true, false
name optional	An optional query to scope Tweets by name. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: dtc
timeline_type optional	Whether to return nullcasted (a.k.a. “Promoted-only”) Tweets, organic Tweets, or both. Type: enum Default: NULLCAST Possible values: ALL, NULLCAST, ORGANIC
trim_user optional	Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet’s author’s user ID. Type: boolean Default: false Possible values: true, false
tweet_ids optional	A comma-separated list of identifiers. Up to 200 IDs may be provided. Note: The IDs should correspond to the specified tweet_type. For example, if a Scheduled Tweet ID is passed in, then the tweet_type must be SCHEDULED in order for that Tweet to be returned in the response. Type: long Example: 1122911801354510336,1102836745790316550
user_id optional	Specifies the user to scope Tweets to. Defaults to the FULL promotable user on the account when not set. Type: long Example: 756201191646691328

Example Request

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

Example Response

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

POST accounts/:account_id/tweet

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

If the authenticated user is not the FULL promotable user on this account, determine if they have permission to Tweet on behalf this user by making a request to the GET accounts/:account_id/authenticated_user_access endpoint. A permission of TWEET_COMPOSER indicates that the user may use this endpoint to create nullcasted Tweets on behalf of the FULL promotable user.

When using the upload.x.com endpoint for media, pass in the same user_id value for the additional_owners parameter as the as_user_id value that you pass in to this endpoint.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
as_user_id required	The user ID of the advertiser on behalf of whom you are posting the Tweet. The advertiser must grant your handle (or handles) access to their ads account via ads.x.com. This permission allows you to call the API using the OAuth tokens of your own handle rather than the advertiser’s. Type: long Example: 756201191646691328
text sometimes required	The text of your status update. Required if no media_keys are specified. Type: string Example: hello, world
card_uri optional	Associate a card with the Tweet using the card_uri value from any cards response, if available. Type: string Example: card://853503245793641682
conversation_settings optional	Choose who can reply to this Tweet. Anyone mentioned can always reply. Note: This field will not be returned in the POST request response, but will be returned when making a GET request. Note: This parameter only works in Ads API v8 and above. Type: enum Default: EVERYONE Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys optional	Associate media with the Tweet by specifying a comma-separated list of identifiers. Include up to 4 images, 1 animated GIF, or 1 video. Type: string Example: 13_1153584529292270722
name optional	The name for the Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name
nullcast optional	Whether to create a nullcasted (or “Promoted-only”) Tweet. Note: Organic Tweets (nullcast=false) can only be created for the authenticated user. Type: boolean Default: true Possible values: true, false
trim_user optional	Whether to exclude the user object in the Tweet response. When enabled, the only part of the user object that will be returned is the Tweet’s author’s user ID. Type: boolean Default: false Possible values: true, false
tweet_mode optional	Whether the response should be in compatibility or extended mode. See this for additional information. Type: string Possible values: compat, extended
video_cta optional	The CTA for the video. Type: enum Possible values: VISIT_SITE, WATCH_NOW
video_cta_value optional	The value for the corresponding CTA on the video. Type: string Example: https://dev.x.com
video_description optional	The description that appears under the video. Maximum length: 200 characters. Type: string Example: Integrate with the X advertising platform
video_title optional	The title (headline) that appears under the video. Maximum length: 70 characters. Type: string Example: X Ads API

Example Request

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

Example Response

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

Update the specified Tweet name belonging to the current account.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
tweet_id required	A reference to the Tweet you are operating with in the request. Type: long Example: 994747471329873920
name optional	The name for the Tweet. Maximum length: 80 characters. Type: string Example: Tweet with name

Example Request

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

Example Response

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

Video Conversation Cards

Note: To associate a card with a Tweet, use the card_uri parameter with either the POST accounts/:account_id/tweet, POST statuses/update, or POST accounts/:account_id/scheduled_tweets endpoints.

GET accounts/:account_id/cards/video_conversation

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_ids optional	Scope the response to just the desired video conversation cards by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: 5a86h
count optional	Specifies the number of records to try and retrieve per distinct request. Type: int Default: 200 Min, Max: 1, 1000
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: 8x7v00oow
q optional	An optional query to scope cards by name. Omit this parameter to retrieve all. Maximum length: 80 characters. Note: This performs case-insensitive prefix matching. Type: string Example: night sky
sort_by optional	Sorts by supported attribute in ascending or descending order. See Sorting for more information. Type: string Example: created_at-asc
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false
with_total_count optional	Include the total_count response attribute. Note: This parameter and cursor are exclusive. Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: 4i0ya
with_deleted optional	Include deleted results in your request. Type: boolean Default: false Possible values: true, false

Example Request

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

Example Response

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

POST accounts/:account_id/cards/video_conversation

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

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
first_cta required	The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: #APIs
first_cta_tweet required	The Tweet text to be used when the first CTA is clicked. Type: string Example: Ads API
media_key required	The media key for a video to be used in this card. Note: The video must be in the account’s Media Library. Note: An aspect ratio of 16:9 is required. Type: string Example: 13_1168079965037467209
name required	The name for the card. Type: string Example: video conversation card
thank_you_text required	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: Build it
title sometimes required	The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if second_cta is not set. Example: Developers
second_cta sometimes required	The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string Note: Required if title is not set. Example: #ShareAgain
second_cta_tweet sometimes required	The Tweet text to be used when the second CTA is clicked. Note: Required if second_cta is set. Type: string Example: I Heart @AdsAPI Again
poster_media_key optional	The media key for a poster image to be used in this card. If not specified, the first frame will be used. Note: The video must be in the account’s Media Library. Type: long Example: 3_882726458191298561
third_cta optional	The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareMore
third_cta_tweet sometimes required	The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if third_cta is set. Example: I Heart @TwitterDev
fourth_cta optional	The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareExtra
fourth_cta_tweet sometimes required	The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if fourth_cta is set. Example: I Heart @TwitterDev Again
thank_you_url optional	The URL to be displayed with the thank you text. Type: string Example: https://example.com/thankyou
unlocked_image_media_key optional	A media_key of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. Note: The image must be in the account’s media library. Type: string Example: 3_883112887618682880
unlocked_video_media_key optional	The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario. Type: string Example: 13_867520357225418752

Example Request

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

Example Response

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

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

See Uploading Media for useful information on uploading images to our endpoints.

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: 5a86h
first_cta optional	The Call-To-Action (CTA) hashtag for the first option. Maximum length: 20 characters (not counting the #). Type: string Example: #APIs
first_cta_tweet optional	The Tweet text to be used when the first CTA is clicked. Type: string Example: Ads API
second_cta optional	The Call-To-Action (CTA) hashtag for the second option. Maximum length: 20 characters (not counting the #). Type: string Note: Required if title is not set. Example: #ShareAgain
second_cta_tweet optional	The Tweet text to be used when the second CTA is clicked. Note: Required if second_cta is set. Type: string Example: I Heart @AdsAPI Again
third_cta optional	The Call-To-Action (CTA) hashtag for the third option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareMore
third_cta_tweet optional	The Tweet text to be used when the third CTA is clicked. Type: string Note: Required if third_cta is set. Example: I Heart @TwitterDev
fourth_cta optional	The Call-To-Action (CTA) hashtag for the fourth option. Maximum length: 20 characters (not counting the #). Type: string Example: #ShareExtra
fourth_cta_tweet optional	The Tweet text to be used when the fourth CTA is clicked. Type: string Note: Required if fourth_cta is set. Example: I Heart @TwitterDev Again
media_key optional	The media key for a video to be used in this card. Note: The video must be in the account’s Media Library. Note: An aspect ratio of 16:9 is required. Type: string Example: 13_1168079965037467209
name optional	The name for the card. Type: string Example: developers card
poster_media_key optional	The media key for a poster image to be used in this card. If not specified, the first frame will be used. Note: The video must be in the account’s Media Library. Type: long Example: 3_882726458191298561
thank_you_text optional	The text to be displayed after the CTA is clicked. Maximum length: 23 characters. Type: string Example: Build it
thank_you_url optional	The URL to be displayed with the thank you text. Type: string Example: https://example.com/thankyou
title optional	The title for the card, which appears below the video and above the CTAs. Maximum length: 23 characters. Type: string Note: Required if second_cta is not set. Example: Start a conversation
unlocked_image_media_key optional	A media_key of an image which will be used in the instant unlock scenario. This is a write-only field. In the response, the API will provide a X URL for this image. Note: The image must be in the account’s media library. Type: string Example: 3_883112887618682880
unlocked_video_media_key optional	The identifier of a video from the GET accounts/:account_id/media_library endpoint which will be used in the instant unlock scenario. Type: string Example: 13_867520357225418752

Example Request

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

Example Response

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

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

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

Resource URL

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

Parameters

Name	Description
account_id required	The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user. Type: string Example: 18ce54d4x5t
card_id required	A reference to the video conversation card you are operating with in the request. Type: string Example: 4i0ya

Example Request

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

Example Response

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