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/4/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: |
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: |
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: |
scoped_to optional |
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: |
user_id optional |
Specifies the user to scope Tweets to. Defaults to the Type: long Example: |
Example Request¶
GET https://ads-api.twitter.com/4/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/4/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: |
text sometimes required |
The text of your status update. Required if no Type: string Example: |
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: |
card_uri optional |
Associate a card with the Tweet using the Type: string Example: |
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: |
nullcast optional |
Whether to create a nullcasted (or "Promoted-only") Tweet. Note: Organic Tweets ( 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: |
video_cta optional |
The CTA for the video. Type: enum Possible values: |
video_cta_value optional |
The value for the corresponding CTA on the video. Type: string Example: |
video_description optional |
The description that appears under the video. Maximum length: 200 characters. Type: string Example: |
video_id optional |
The identifier of a video from the GET accounts/:account_id/media_library endpoint to be included in the Tweet. Type: string Example: |
video_title optional |
The title (headline) that appears under the video. Maximum length: 70 characters. Type: string Example: |
Example Request¶
POST http://ads-api.twitter.com/4/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/4/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: |
text sometimes required |
The text of your status update. Required if no Type: string Example: |
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: |
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: |
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/media_library endpoint to be included in the preview. Type: string Example: |
Example Request¶
GET https://ads-api.twitter.com/4/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' data-tweet-id='"1"' tweet="" tweet--web=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <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' data-tweet-id='"1"' tweet="" tweet--android=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <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' data-tweet-id='"1"' tweet="" tweet--iphone=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <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/4/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: |
tweet_id required |
The unique identifier referring to a Tweet. Type: long Example: |
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/4/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' data-tweet-id='"880950824339419136"' tweet="" tweet--web=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <span class='"Tweet-name"'>API McTestface</span> <span class='"Tweet-screenName"'>@apimctestface</span> </a> </div> <small class='"Tweet-timeLabel"'> <a class='"Tweet-timestamp"' data-time='"1498870018"' href='"https://twitter.com/apimctestface/status/880950824339419136"' target='"_blank"'> 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' data-tweet-id='"880950824339419136"' tweet="" tweet--android=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <span class='"Tweet-name"'>API McTestface</span> <span class='"Tweet-screenName"'>@apimctestface</span> </a> </div> <small class='"Tweet-timeLabel"'> <a class='"Tweet-timestamp"' data-time='"1498870018"' href='"https://twitter.com/apimctestface/status/880950824339419136"' target='"_blank"'> 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' data-tweet-id='"880950824339419136"' tweet="" tweet--iphone=""> <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"'> <a class='"Tweet-userLink"' href='"https://twitter.com/apimctestface"' target='"_blank"'> <span class='"Tweet-name"'>API McTestface</span> <span class='"Tweet-screenName"'>@apimctestface</span> </a> </div> <small class='"Tweet-timeLabel"'> <a class='"Tweet-timestamp"' data-time='"1498870018"' href='"https://twitter.com/apimctestface/status/880950824339419136"' target='"_blank"'> 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"
}
}
}