scheduled-tweets

Scheduled Tweets

GET accounts/:account_id/scheduled_tweets¶

Retrieve details for some or all Scheduled Tweets associated with the current account.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/scheduled_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: `100` Min, Max: `1`, `200`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `c-j3cn6n40`
user_id optional	Specify the user to retrieve Scheduled Tweets for. 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/scheduled_tweets?count=1

Example Response¶

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "test name",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "where you want to be",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id¶

Retrieve a specific Scheduled Tweet associated with the current account.

Resource URL¶

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

scheduled_tweet_id
required

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

Type: string

Example: 917438609065623552

Example Request¶

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

Example Response¶

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

POST accounts/:account_id/scheduled_tweets¶

Create a Scheduled Tweet for the account's full promotable user (default) or the user specified in the as_user_id parameter.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/scheduled_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`
scheduled_at required	The time, expressed in ISO 8601, that the Tweet should be published (or go live). Note: Tweets can only be scheduled up to one year in the future. Note: Tweets should only be scheduled at minute-granularity; seconds will be ignored. Type: string Example: `2017-12-31T23:59:00Z`
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: `just setting up my twttr`
card_uri optional	Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Type: string Example: `card://855591459410511943`
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. Note: The media asset must be in the account's Media Library. Type: string Example: `13_1153584529292270722`
nullcast optional	Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Default: `true` Possible values: `true`, `false`
name optional	The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name`

Example Request¶

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01

Example Response¶

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id¶

Update the specified Scheduled Tweet belonging to the current account.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_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`
scheduled_tweet_id required	A reference to the Scheduled Tweet you are operating with in the request. Type: string Example: `870321875435442177`
card_uri optional	Associate a card with the Tweet using the `card_uri` value from any cards response, if available. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: `card://875146925316386347`
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. Note: The media asset must be in the account's Media Library. Note: Unset (remove) by specifying the parameter without a value. Type: string Example: `13_1153584529292270722`
nullcast optional	Whether to create a nullcasted (or "Promoted-only") Tweet. Type: boolean Possible values: `true`, `false`
scheduled_at optional	The time, expressed in ISO 8601, that the Tweet should be published (or go live). Type: string Example: `2017-12-31T23:59:59Z`
text optional	The text of your status update. Type: string Example: `just setting up my twttr`
name optional	The name for the Scheduled Tweet. Maximum length: 80 characters. Type: string Example: `Tweet with name`

Example Request¶

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice

Example Response¶

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "winter solstice"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "winter solstice",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id¶

Permanently delete the specified Scheduled Tweet belonging to the current account.

Note: This is a hard delete. As a result, it is not possible to retrieve deleted Scheduled Tweets.

Resource URL¶

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

Parameters¶

Name Description

account_id
required

Type: string

Example: 18ce54d4x5t

scheduled_tweet_id
required

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

Type: string

Example: 870321875435442177

Example Request¶

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

Example Response¶

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "hello, world",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}