Promoted Tweets
promoted-tweets

Promoted Tweets

Run in Postman ❯ 

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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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.x.com/12/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"
    }
  }
}