Creatives

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.twitter.com/3/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.twitter.com/3/accounts/18ce54d4x5t/scheduled_tweets?count=1

Example Response

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "completed_at": "2017-06-18T22:00:05Z",
      "id_str": "875828692081037312",
      "text": "where you want to be",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": 875828692081037312,
      "media_ids": [
        "875828691770548224"
      ],
      "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"
}

GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

Retrieve a specific Scheduled Tweet associated with the current account.

Resource URL

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

Example: 917438609065623552

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": 917438609065623552
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917438609065623552",
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": 917438609065623552,
    "media_ids": [
      "917438348871983104"
    ],
    "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.twitter.com/3/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
text
sometimes required

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

Type: string

Example: just setting up my twttr
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://855591459410511943
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: 870320790339637248
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/3/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_ids=917438348871983104&scheduled_at=2018-01-01

Example Response

{
  "request": {
    "params": {
      "media_ids": [
        917438348871983104
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917438609065623552",
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": 917438609065623552,
    "media_ids": [
      "917438348871983104"
    ],
    "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"
    ]
  }
}

PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

Update the specified Scheduled Tweet belonging to the current account.

Resource URL

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

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_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: 870320790339637248
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

Example Request

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

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875057751231037440,
      "text": "winter solstice"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "875057751231037440",
    "scheduled_status": "SCHEDULED",
    "text": "winter solstice",
    "user_id": "756201191646691328",
    "id": 875057751231037440,
    "media_ids": null,
    "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": []
  }
}

DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

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

Example: 870321875435442177

Example Request

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "875064008595787776",
    "scheduled_status": "DELETED",
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": 875064008595787776,
    "media_ids": null,
    "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": []
  }
}

GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id

Preview a Scheduled 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/3/accounts/:account_id/scheduled_tweets/preview/: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: long

Example: 919331596020285440

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/scheduled_tweets/preview/919331596020285440

Example Response

{
  "request": {
    "params": {
      "scheduled_tweet_id": 919331596020285440
    }
  },
  "data": [
    {
      "platform": "web",
      "preview": "<!DOCTYPE html> <html> <head>   <meta charset="utf-8" />      <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.cb572b35a753a67c4416.css" rel="stylesheet" /> </head>  <body>       <div class="Tweet--timeline   Tweet   Tweet--web          "  data-tweet-id="919331596020285440">    <img class="Tweet-avatar" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48" height="48" alt=""/>    <div class="Tweet-body">     <div class="Tweet-header">       <div class="Tweet-userData">         <a href="https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span>                            <span class="Tweet-screenName">@apimctestface</span>         </a>       </div>         <span class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Oct 31         </span>       </span>     </div>         <div class="Tweet-text " dir="">video w/o</div>           <div class="CardContainer   CardContainer--timeline       CardContainer--web    " >             <div class="VideoCard">      <div class="Card-video">           <iframe class="Card-videoIframe"       src="https://twitter.com/i/videos/static?json_rpc=1&square_corners=1&image_src=https%3A%2F%2Fpbs%2Etwimg%2Ecom%2Famplify_video_thumb%2F887777498917777408%2Fimg%2FcwavyNV2brPoEOlK%2Ejpg&video_url=https%3A%2F%2Fvideo%2Etwimg%2Ecom%2Famplify_video%2F887777498917777408%2Fvid%2F1280x720%2F35qJ3AUkmYIWfLGT%2Emp4"></iframe>      <button class="Card-videoPosterImageContainer">       <img alt="" class="Card-videoPosterImage" src="https://pbs.twimg.com/amplify_video_thumb/887777498917777408/img/cwavyNV2brPoEOlK.jpg" />       <span class="Card-videoPosterImagePlayButton Icon Icon--playButton"></span>     </button> </div>    </div>              </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>    </div> </div>   </body> </html> "
    },
    {
      "platform": "android",
      "preview": "<!DOCTYPE html> <html> <head>   <meta charset="utf-8" />      <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.cb572b35a753a67c4416.css" rel="stylesheet" /> </head>  <body>       <div class="Tweet--timeline   Tweet   Tweet--android          "  data-tweet-id="919331596020285440">    <img class="Tweet-avatar" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48" height="48" alt=""/>    <div class="Tweet-body">     <div class="Tweet-header">       <div class="Tweet-userData">         <a href="https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span>                            <span class="Tweet-screenName">@apimctestface</span>         </a>       </div>         <span class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Oct 31         </span>       </span>     </div>         <div class="Tweet-text " dir="">video w/o</div>           <div class="CardContainer   CardContainer--timeline       CardContainer--android    " >             <div class="VideoCard">      <div class="Card-video">           <iframe class="Card-videoIframe"       src="https://twitter.com/i/videos/static?json_rpc=1&square_corners=1&image_src=https%3A%2F%2Fpbs%2Etwimg%2Ecom%2Famplify_video_thumb%2F887777498917777408%2Fimg%2FcwavyNV2brPoEOlK%2Ejpg&video_url=https%3A%2F%2Fvideo%2Etwimg%2Ecom%2Famplify_video%2F887777498917777408%2Fvid%2F1280x720%2F35qJ3AUkmYIWfLGT%2Emp4"></iframe>      <button class="Card-videoPosterImageContainer">       <img alt="" class="Card-videoPosterImage" src="https://pbs.twimg.com/amplify_video_thumb/887777498917777408/img/cwavyNV2brPoEOlK.jpg" />       <span class="Card-videoPosterImagePlayButton Icon Icon--playButton"></span>     </button> </div>    </div>              </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>    </div> </div>   </body> </html> "
    },
    {
      "platform": "iphone",
      "preview": "<!DOCTYPE html> <html> <head>   <meta charset="utf-8" />      <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.cb572b35a753a67c4416.css" rel="stylesheet" /> </head>  <body>       <div class="Tweet--timeline   Tweet   Tweet--iphone          "  data-tweet-id="919331596020285440">    <img class="Tweet-avatar" src="https://pbs.twimg.com/profile_images/756348317458509825/DTKcRCpS_normal.jpg" width="48" height="48" alt=""/>    <div class="Tweet-body">     <div class="Tweet-header">       <div class="Tweet-userData">         <a href="https://twitter.com/apimctestface" target="_blank" class="Tweet-userLink">           <span class="Tweet-name">API McTestface</span>                            <span class="Tweet-screenName">@apimctestface</span>         </a>       </div>         <span class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Oct 31         </span>       </span>     </div>         <div class="Tweet-text " dir="">video w/o</div>           <div class="CardContainer   CardContainer--timeline       CardContainer--iphone    " >             <div class="VideoCard">      <div class="Card-video">           <iframe class="Card-videoIframe"       src="https://twitter.com/i/videos/static?json_rpc=1&square_corners=1&image_src=https%3A%2F%2Fpbs%2Etwimg%2Ecom%2Famplify_video_thumb%2F887777498917777408%2Fimg%2FcwavyNV2brPoEOlK%2Ejpg&video_url=https%3A%2F%2Fvideo%2Etwimg%2Ecom%2Famplify_video%2F887777498917777408%2Fvid%2F1280x720%2F35qJ3AUkmYIWfLGT%2Emp4"></iframe>      <button class="Card-videoPosterImageContainer">       <img alt="" class="Card-videoPosterImage" src="https://pbs.twimg.com/amplify_video_thumb/887777498917777408/img/cwavyNV2brPoEOlK.jpg" />       <span class="Card-videoPosterImagePlayButton Icon Icon--playButton"></span>     </button> </div>    </div>              </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>    </div> </div>   </body> </html> "
    }
  ]
}