Campaign Management

Promotable Users

GET accounts/:account_id/promotable_users

Retrieve details for some or all promotable users associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account.

Advertisers must obtain permission to promote another user’s content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/promotable_users

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: 8x7v00oow
promotable_user_ids
optional

Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: l310s
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional

Include the total_count response attribute.

Note: This parameter will be ignored if cursor is specified.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response

{
  "request": {
    "params": {
      "promotable_user_ids": [
        "l310s"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "user_id": "756201191646691328",
      "id": "l310s",
      "account_id": "18ce54d4x5t",
      "created_at": "2016-07-21T22:42:09Z",
      "updated_at": "2016-07-21T22:42:09Z",
      "deleted": false,
      "promotable_user_type": "FULL"
    }
  ]
}

GET accounts/:account_id/promotable_users/:promotable_user_id

Retrieve a specific promotable user associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account.

Advertisers must obtain permission to promote another user’s content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/promotable_users/:promotable_user_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
promotable_user_id
optional

A reference to the promotable user you are operating on within the request

Type: string

Example: l310s
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/promotable_users/l310s

Example Response

{
  "request": {
    "params": {
      "promotable_user_id": "l310s",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "user_id": "2417045708",
    "id": "l310s",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-03-10T17:51:24Z",
    "updated_at": "2017-03-10T17:51:24Z",
    "deleted": false,
    "promotable_user_type": "RETWEETS_ONLY"
  }
}