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: |
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/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: |
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/videos 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/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: |
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/videos endpoint to be included in the preview. Type: string Example: |
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: |
tweet_id
required
|
The unique identifier referring to a Tweet. Type: long 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: |
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"
}
}
}