Tweets
tweets

Tweets

Run in Postman ❯ 

GET accounts/:account_id/tweets

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.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/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
tweet_type
required

The Tweet type for the specified tweet_ids.

Type: enum

Possible values: DRAFT, PUBLISHED, SCHEDULED
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
include_mentions_and_replies
optional

Whether to filter out mentions and replies from the list of available Tweets.

Type: boolean

Default: false
Possible values: true, false
name
optional

An optional query to scope Tweets by name. Omit this parameter to retrieve all. Maximum length: 80 characters.

Note: This performs case-insensitive prefix matching.

Type: string

Example: dtc
timeline_type
optional

Whether to return nullcasted (a.k.a. "Promoted-only") Tweets, organic Tweets, or both.

Type: enum

Default: NULLCAST
Possible values: ALL, NULLCAST, ORGANIC
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_ids
optional

A comma-separated list of identifiers. Up to 200 IDs may be provided.

Note: The IDs should correspond to the specified tweet_type. For example, if a Scheduled Tweet ID is passed in, then the tweet_type must be SCHEDULED in order for that Tweet to be returned in the response.

Type: long

Example: 1122911801354510336,1102836745790316550
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.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

Example Response

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "EVERYONE",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

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.

Resource URL

https://ads-api.x.com/12/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
as_user_id
required

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
text
sometimes required

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

Type: string

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

Choose who can reply to this Tweet. Anyone mentioned can always reply.

Note: This field will not be returned in the POST request response, but will be returned when making a GET request.

Note: This parameter only works in Ads API v8 and above.

Type: enum

Default: EVERYONE
Possible values: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys
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.

Type: string

Example: 13_1153584529292270722
name
optional

The name for the Tweet. Maximum length: 80 characters.

Type: string

Example: Tweet with name
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_title
optional

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

Type: string

Example: Twitter Ads API

Example Request

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

PUT accounts/:account_id/tweets/:tweet_id/name

Update the specified Tweet name belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

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

A reference to the Tweet you are operating with in the request.

Type: long

Example: 994747471329873920
name
optional

The name for the Tweet. Maximum length: 80 characters.

Type: string

Example: Tweet with name

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

Example Response

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "new Tweet name",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "new Tweet name",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">Ads API Internal Test App</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "hello",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Sorcerer / Partner Engineer @twitter / Space Traveller | Former evangelist @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}