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.twitter.com/5/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: long

Example: 756201191646691328

Example Request

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

Example Response

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "id_str": "994791681219231744",
      "text": "hello, world",
      "user_id": "756201191646691328",
      "id": 994791681219231744,
      "media_ids": [],
      "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"
}

GET accounts/:account_id/draft_tweets/:draft_tweet_id

Retrieve a specific Draft Tweet associated with the current account.

Resource URL

https://ads-api.twitter.com/5/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: long

Example: 994788364334325760

Example Request

GET https://ads-api.twitter.com/5/accounts/18ce54d4x5t/draft_tweets/994788364334325760

Example Response

{
  "request": {
    "params": {
      "draft_tweet_id": 994788364334325760
    }
  },
  "data": {
    "id_str": "994788364334325760",
    "text": "#TwitterDev",
    "user_id": "756201191646691328",
    "id": 994788364334325760,
    "media_ids": [],
    "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.twitter.com/5/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

text
sometimes required

The text of your status update. Required if no media_ids are specified.

Type: string

Example: Just setting up my Twitter.

as_user_id
optional

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

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_ids
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. See Uploading Media for additional details on uploading media.

Type: long

Example: 973143684214158061

nullcast
optional

Whether to create a nullcasted (or "Promoted-only") Tweet.

Type: boolean

Default: true
Possible values: true, false

Example Request

POST https://ads-api.twitter.com/5/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my Twitter.

Example Response

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

PUT accounts/:account_id/draft_tweets/:draft_tweet_id

Update the specified Draft Tweet belonging to the current account.

Resource URL

https://ads-api.twitter.com/5/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: long

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_ids
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. See Uploading Media for additional details on uploading media.

Note: Unset (remove) by specifying the parameter without a value.

Type: long

Example: 984137759226786305

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

Example Request

PUT https://ads-api.twitter.com/5/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": {
    "id_str": "994747471329873920",
    "text": "just setting up my twttr",
    "user_id": "756201191646691328",
    "id": 994747471329873920,
    "media_ids": [],
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

DELETE accounts/:account_id/draft_tweets/:draft_tweet_id

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.twitter.com/5/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: long

Example: 994787835663155200

Example Request

DELETE https://ads-api.twitter.com/5/accounts/18ce54d4x5t/draft_tweets/994787835663155200

Example Response

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

GET accounts/:account_id/draft_tweets/preview/:draft_tweet_id

Preview a Draft Tweet as it would appear across a variety of different platforms: Android, iPhone, and Web.

The JSON response will contain the preview HTML. This is a fully functional HTML document that is ready to be used to render a preview in a browser. The relevant CSS and images will be served directly via Twitter.

Note: Previews are approximate.

Resource URL

https://ads-api.twitter.com/5/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: long

Example: 994787185084850178

Example Request

GET https://ads-api.twitter.com/5/accounts/18ce54d4x5t/draft_tweets/preview/994787185084850178

Example Response

{
  "request": {
    "params": {
      "draft_tweet_id": 994787185084850178
    }
  },
  "data": [
    {
      "platform": "web",
      "preview": "<!DOCTYPE html>
 <html> <head> <meta charset="utf-8"/> <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.fd70c3bf20e76566b2d9.css" rel="stylesheet"/> </head> <body> <div class="Tweet--timeline Tweet Tweet--web " data-tweet-id="994787185084850178"> <img alt="" class="Tweet-avatar" height="48" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48"/> <div class="Tweet-body"> <div class="Tweet-header"> <div class="Tweet-userData">         [       <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg"/>     ](https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span> <span class="Tweet-screenName">@apimctestface</span> </div></div></div></div></body></html>   <div class="Tweet-text " dir=""></div> <div class="Tweet-photoGallery Tweet-photoGallery--photos2"> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position1 " href="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg" target="_blank"> <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg"/> </a> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position2 " href="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg" target="_blank) </div>     </div>     <div class=" tweet-footer"=""> <div class="Tweet-actions "> <button class="Tweet-action Tweet-action--reply" type="button"> <span class="Icon Icon--reply"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--retweet" type="button"> <span class="Icon Icon--retweet"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--favorite Tweet-action--like" type="button"> <span class="Icon Icon--heart"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--dm" type="button"> <span class="Icon Icon--dm"></span> </button> </div> <div class="Tweet-context Tweet-context--promotion"> <div class="Tweet-badge Tweet-badge--promotedBy"> <span class="Icon Icon--promoted"></span> <span class="Tweet-badgeText">Promoted</span> </div> </div> </a></div>    "
    },
    {
      "platform": "android",
      "preview": "<!DOCTYPE html>
 <html> <head> <meta charset="utf-8"/> <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.fd70c3bf20e76566b2d9.css" rel="stylesheet"/> </head> <body> <div class="Tweet--timeline Tweet Tweet--android " data-tweet-id="994787185084850178"> <img alt="" class="Tweet-avatar" height="48" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48"> <div class="Tweet-body"> <div class="Tweet-header"> <div class="Tweet-userData">         [       <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg"/>     ](https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span> <span class="Tweet-screenName">@apimctestface</span> </div></div></div></img></div></body></html>   <div class="Tweet-text " dir=""></div> <div class="Tweet-photoGallery Tweet-photoGallery--photos2"> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position1 " href="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg" target="_blank"> <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg"/> </a> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position2 " href="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg" target="_blank) </div>     </div>     <div class=" tweet-footer"=""> <div class="Tweet-actions "> <button class="Tweet-action Tweet-action--reply" type="button"> <span class="Icon Icon--reply"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--retweet" type="button"> <span class="Icon Icon--retweet"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--favorite Tweet-action--like" type="button"> <span class="Icon Icon--heart"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--dm" type="button"> <span class="Icon Icon--dm"></span> </button> </div> <div class="Tweet-context Tweet-context--promotion"> <div class="Tweet-badge Tweet-badge--promotedBy"> <span class="Icon Icon--promoted"></span> <span class="Tweet-badgeText">Promoted</span> </div> </div> </a></div>    "
    },
    {
      "platform": "iphone",
      "preview": "<!DOCTYPE html>
 <html> <head> <meta charset="utf-8"/> <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.fd70c3bf20e76566b2d9.css" rel="stylesheet"/> </head> <body> <div class="Tweet--timeline Tweet Tweet--iphone " data-tweet-id="994787185084850178"> <img alt="" class="Tweet-avatar" height="48" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48"> <div class="Tweet-body"> <div class="Tweet-header"> <div class="Tweet-userData">         [       <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg"/>     ](https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span> <span class="Tweet-screenName">@apimctestface</span> </div></div></div></img></div></body></html>   <div class="Tweet-text " dir=""></div> <div class="Tweet-photoGallery Tweet-photoGallery--photos2"> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position1 " href="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg" target="_blank"> <img alt="Embedded image permalink" class="Tweet-photoGalleryPhoto" src="https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg"/> </a> <a class="Tweet-photoGalleryCell Tweet-photoGalleryCell--position2 " href="https://pbs.twimg.com/media/DUfy_2JU8AAMAOk.jpg" target="_blank) </div>     </div>     <div class=" tweet-footer"=""> <div class="Tweet-actions "> <button class="Tweet-action Tweet-action--reply" type="button"> <span class="Icon Icon--reply"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--retweet" type="button"> <span class="Icon Icon--retweet"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--favorite Tweet-action--like" type="button"> <span class="Icon Icon--heart"></span> <span class="Tweet-actionCount">##</span> </button> <button class="Tweet-action Tweet-action--dm" type="button"> <span class="Icon Icon--dm"></span> </button> </div> <div class="Tweet-context Tweet-context--promotion"> <div class="Tweet-badge Tweet-badge--promotedBy"> <span class="Icon Icon--promoted"></span> <span class="Tweet-badgeText">Promoted</span> </div> </div> </a></div>    "
    }
  ]
}

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 Twitter official apps.

Resource URL

https://ads-api.twitter.com/5/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: long

Example: 996132315829948416

Example Request

POST https://ads-api.twitter.com/5/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416

Example Response

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