Creatives

Tweets

GET accounts/:account_id/scoped_timeline

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.

This endpoint will only return Tweets created after the Ads account for the corresponding @handle is activated. The recommended approach to backfilling all Tweets is to use the GET statuses/user_timeline to retrieve all the Tweets for the handle and use this endpoint for all subsequent requests.

Note: When filtering by objective, we will fetch the first set of promotable Tweets and then filter those appropriate for the objective. This results in inconsistent page sizes in the results. If a next_cursor is returned, there are additional Tweets available for this filter.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/scoped_timeline

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: 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
objective
optional

Filter the results to only those Tweets appropriate for the given objective. See note above (top of page) about how filtering by objective affects result paging.

Type: enum

Possible values: APP_ENGAGEMENTS, APP_INSTALLS, AWARENESS, FOLLOWERS, TWEET_ENGAGEMENTS, VIDEO_VIEWS, VIDEO_VIEWS_PREROLL, WEBSITE_CLICKS
scoped_to
optional

followers to find Tweets in the users’s timeline or none to find nullcasted Tweets.

Type: string

Default: followers
Possible values: followers, none
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
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.twitter.com/3/accounts/18ce54d4x5t/scoped_timeline?scoped_to=none&trim_user=true&count=1

Example Response

{
  "data": [
    {
      "created_at": "Sat Jul 01 00:46:58 +0000 2017",
      "id": 880950824339419136,
      "id_str": "880950824339419136",
      "text": "hello, world",
      "truncated": false,
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "source": "<a href="https://ads-api.twitter.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": [
        2417045708
      ],
      "retweet_count": 0,
      "favorite_count": 0,
      "favorited": false,
      "retweeted": false,
      "scopes": {
        "followers": false
      },
      "lang": "en"
    }
  ],
  "next_cursor": "AAAAAFhLRpQLNF-sGBSgAA",
  "request": {
    "params": {
      "trim_user": true,
      "count": 1,
      "scoped_to": "none",
      "account_id": "18ce54d4x5t"
    }
  }
}

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

To retrieve Tweets, use GET accounts/:account_id/scoped_timeline endpoint.

Resource URL

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

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

Type: string

Example: hello, world
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://853503245793641682
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.

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.twitter.com
video_description
optional

The description that appears under the video. Maximum length: 200 characters.

Type: string

Example: Integrate with the Twitter advertising platform
video_id
optional

The identifier of a video from the GET accounts/:account_id/videos endpoint to be included in the Tweet.

Type: string

Example: 13_860318603387600896
video_title
optional

The title (headline) that appears under the video. Maximum length: 70 characters.

Type: string

Example: Twitter Ads API

Example Request

POST http://ads-api.twitter.com/3/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",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href="https://ads-api.twitter.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"
    }
  }
}

GET accounts/:account_id/tweet/preview

Preview a Tweet that does not already exist as it would appear across a variety of different platforms; iPhone, Android and Web. You can preview a Tweet both for how it will look like on Twitter or on the Twitter Audience Platform (TAP).

The returned JSON response will contain the preview HTML; this is a fully functional HTML document that is ready to be used to render a preview Tweet 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/tweet/preview

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: hello, world
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
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
preview_target
optional

The target to render the Tweet preview for.

Type: enum

Default: TWITTER_TIMELINE
Possible values: PUBLISHER_NETWORK, TWITTER_TIMELINE
video_id
optional

The identifier of a video from the GET accounts/:account_id/videos endpoint to be included in the preview.

Type: string

Example: 13_874389195671043237

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/tweet/preview?text=hello, world&as_user_id=756201191646691328

Example Response

{
  "data": [
    {
      "platform": "web",
      "preview": "<!DOCTYPE html> <html> <head>   <meta charset="utf-8" />      <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.2c0aa44569611941aea3.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--web          "  data-tweet-id="1">    <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>         <small class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Dec 31         </span>       </small>     </div>       <div class="Tweet-text " dir="">hello, world</div>       </div>     <div class="Tweet-footer">          <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></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.2c0aa44569611941aea3.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--android          "  data-tweet-id="1">    <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>         <small class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Dec 31         </span>       </small>     </div>       <div class="Tweet-text " dir="">hello, world</div>       </div>     <div class="Tweet-footer">          <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></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.2c0aa44569611941aea3.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--iphone          "  data-tweet-id="1">    <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>         <small class="Tweet-timeLabel">         <span class="Tweet-timestamp">           <span class="Icon Icon--clock"></span>           Dec 31         </span>       </small>     </div>       <div class="Tweet-text " dir="">hello, world</div>       </div>     <div class="Tweet-footer">          <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></span>      <span class="Tweet-badgeText">Promoted</span>   </div> </div>    </div> </div>   </body> </html> "
    }
  ],
  "request": {
    "params": {
      "text": "hello, world",
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

GET accounts/:account_id/tweet/preview/:tweet_id

Preview an existing Tweet as it would appear across a variety of different platforms: Android, iPhone, and Web. You can preview a Tweet both for how it will look like on Twitter or on the Twitter Audience Platform (TAP).

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 Tweet 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/tweet/preview/: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
tweet_id
required

The unique identifier referring to a Tweet.

Type: long

Example: 880950824339419136
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
preview_target
optional

The target to render the Tweet preview for.

Type: enum

Default: TWITTER_TIMELINE
Possible values: PUBLISHER_NETWORK, TWITTER_TIMELINE

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/tweet/preview/880950824339419136

Example Response

{
  "data": [
    {
      "platform": "web",
      "preview": "<!DOCTYPE html> <html> <head>   <meta charset="utf-8" />      <link href="https://ton.twimg.com/macaw-campaigns/css/tweet_preview.bundle.9a4a0f65a6b27036d306.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--web          "  data-tweet-id="880950824339419136">    <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>        <small class="Tweet-timeLabel">         <a class="Tweet-timestamp" href="https://twitter.com/apimctestface/status/880950824339419136" target="_blank" data-time="1498870018">           Jun 30         </a>       </small>      </div>       <div class="Tweet-text " dir="">hello, world</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> </div>           <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></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.9a4a0f65a6b27036d306.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--android          "  data-tweet-id="880950824339419136">    <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>        <small class="Tweet-timeLabel">         <a class="Tweet-timestamp" href="https://twitter.com/apimctestface/status/880950824339419136" target="_blank" data-time="1498870018">           Jun 30         </a>       </small>      </div>       <div class="Tweet-text " dir="">hello, world</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> </div>           <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></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.9a4a0f65a6b27036d306.css" rel="stylesheet" /> </head>  <body>     <div class="Tweet--timeline Tweet   Tweet--iphone          "  data-tweet-id="880950824339419136">    <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>        <small class="Tweet-timeLabel">         <a class="Tweet-timestamp" href="https://twitter.com/apimctestface/status/880950824339419136" target="_blank" data-time="1498870018">           Jun 30         </a>       </small>      </div>       <div class="Tweet-text " dir="">hello, world</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> </div>           <div class="Tweet-context Tweet-context--promotion">   <div class="Tweet-badge Tweet-badge--promotedBy">      <span class="Icon Icon--promoted Icon--small"></span>      <span class="Tweet-badgeText">Promoted</span>   </div> </div>    </div> </div>   </body> </html> "
    }
  ],
  "request": {
    "params": {
      "tweet_id": "880950824339419136",
      "account_id": "18ce54d4x5t"
    }
  }
}