Tweets

Introduction

The Twitter Ads API supports three types of Tweets: published, scheduled, and draft.

Nullcasted Tweets

Tweets may either be nullcasted (a.k.a. "Promoted-only") or organic. Nullcasted Tweets, once published, do not appear in the user's public timeline, though they are public. Organic Tweets, on the other hand, are served to the user's followers and do appear in the user's public timeline.

Creating Tweets

Each of the three Tweet create endpoints supports a Boolean nullcast parameter that gives the API user the option to create nullcasted or organic Tweets. Nullcasted Tweets can be created by the user or by anyone who has permission to create Tweets on the user's behalf. Organic Tweets can only be created by the full promotable user.

Updating Tweets

It is possible to update the nullcast property for scheduled and draft Tweets. For scheduled Tweets, edits can be made until the Tweet's scheduled_at time. Draft Tweets can be edited indefinitely. Once published, though, it's not possible to change a Tweet from nullcasted to organic or vice versa.

Promoting Tweets

Only published and scheduled Tweets may be promoted. These can either be nullcasted or organic; there's no restriction. An advertiser may promote their own Tweets or another user's Tweets as long as they've obtained permission to do so. (See: Promoting another user's Tweets for more information.)

Multiple Tweets can be promoted in a single campaign. Similarly, a single Tweet may be promoted in one or more campaigns.

To promote published Tweets, use the POST accounts/:account_id/promoted_tweets endpoint. This associates published Tweets with a line item. To promote scheduled Tweets, use the POST accounts/:account_id/scheduled_promoted_tweets endpoint.

Tweet IDs

Published, scheduled, and draft Tweet IDs are numeric—they are 64-bit unsigned integers. For example, the following published Tweet's ID is 1166476031668015104.

When published or scheduled Tweets are promoted, a corresponding promoted Tweet entity is created. These entities have their own IDs, which are alpha-numeric and are represented as base-36-encoded values. For example, promoting the published Tweet above—that is, associating it a line item 6c62d—returns the following API response.

$ twurl -X POST -H ads-api.twitter.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

In addition to the Tweet ID and the line item ID, which were passed into the create request, the response includes an id field with a value of 3qw1q6, which is the promoted Tweet ID.