Promoted Tweets

GET accounts/:account_id/promoted_tweets

Retrieve references to Tweets associated with line items under the current account.

Use the GET accounts/:account_id/tweets endpoint to fetch the Tweet objects. Use the tweet_id values for each promoted_tweets object.

Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response).

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/promoted_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

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

line_item_ids
optional

Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 96uzp

promoted_tweet_ids
optional

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

Type: string

Example: 1efwlo

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 and cursor are exclusive.

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/8/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo

Example Response

{
  "request": {
    "params": {
      "promoted_tweet_ids": [
        "1efwlo"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "96uzp",
      "id": "1efwlo",
      "entity_status": "ACTIVE",
      "created_at": "2017-06-29T05:06:57Z",
      "updated_at": "2017-06-29T05:08:46Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "880290790664060928",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/promoted_tweets/:promoted_tweet_id

Retrieve a specific reference to a Tweet associated with a line item under the current account.

Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response).

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/promoted_tweets/:promoted_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

promoted_tweet_id
required

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

Type: string

Example: 1efwlo

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/8/accounts/18ce54d4x5t/promoted_tweets/1efwlo

Example Response

{
  "request": {
    "params": {
      "promoted_tweet_id": "1efwlo",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "96uzp",
    "id": "1efwlo",
    "entity_status": "ACTIVE",
    "created_at": "2017-06-29T05:06:57Z",
    "updated_at": "2017-06-29T05:08:46Z",
    "approval_status": "ACCEPTED",
    "tweet_id": "880290790664060928",
    "deleted": false
  }
}

POST accounts/:account_id/promoted_tweets

Associate one or more Tweets with the specified line item. Not all Tweets are appropriate for promotion, depending on the campaign objective. Please see Objective-based Campaigns for more information.

When using the PROMOTED_ACCOUNT product type, associating a Tweet with the line_item will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT placement.

Note: It is not possible to update (PUT) promoted Tweet entities.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/promoted_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

line_item_id
required

A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo

tweet_ids
required

A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.

Type: long

Example: 822333526255120384

Example Request

POST https://ads-api.twitter.com/8/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384

Example Response

{
  "data": [
    {
      "line_item_id": "8v7jo",
      "id": "1e8i2k",
      "entity_status": "ACTIVE",
      "created_at": "2017-06-24T04:21:36Z",
      "updated_at": "2017-06-24T04:21:36Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "822333526255120384",
      "deleted": false
    }
  ],
  "request": {
    "params": {
      "line_item_id": "8v7jo",
      "tweet_ids": [
        822333526255120384
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "total_count": 1
}

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

Disassociate a Tweet from the specified line item.

Note: A deleted promoted_tweets entity will be displayed as "Paused" in the ads.twitter.com UI. Similarly, "pausing" from the UI will disassociate the Tweet from its line item.

Resource URL

https://ads-api.twitter.com/8/accounts/:account_id/promoted_tweets/:promoted_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

promoted_tweet_id
required

The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the id field from a response item to GET accounts/:account_id/promoted_tweets, not the tweet_id of the Tweet in question. Supplied within the resource's path.

Type: string

Example: 1gp8a5

Example Request

DELETE https://ads-api.twitter.com/8/accounts/18ce54d4x5t/promoted_tweets/1gp8a5

Example Response

{
  "data": {
    "line_item_id": "9pl99",
    "id": "1gp8a5",
    "entity_status": "ACTIVE",
    "created_at": "2017-08-17T17:02:21Z",
    "updated_at": "2017-08-18T06:43:48Z",
    "approval_status": "ACCEPTED",
    "tweet_id": "844796297743757315",
    "deleted": true
  },
  "request": {
    "params": {
      "promoted_tweet_id": "1gp8a5",
      "account_id": "18ce54d4x5t"
    }
  }
}

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.