Creatives

Account Media

GET accounts/:account_id/account_media

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

Resource URL

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

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
account_media_ids
optional

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

Type: string

Example: 3wpx
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
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/account_media?account_media_ids=3wpx

Example Response

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "account_id": "18ce54d4x5t",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/account_media/:account_media_id

Retrieve a specific account media object associated with the current account.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/account_media/:account_media_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
account_media_id
required

A reference to the account media you are operating with in the request.

Type: string

Example: 2pnfd
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/account_media/2pnfd

Example Response

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

POST accounts/:account_id/account_media

Associate an image or video with the current account.

These entities cannot be added to specific Tweets. Instead, they can be promoted using the POST accounts/:account_id/media_creatives endpoint, which associates the media with a line item. Videos are promoted as in-stream ads and images are promoted based on the media's creative_type on the Twitter Audience Platform.

Upload images using the POST media/upload endpoint. Videos are uploaded using the POST media/upload (chunked) endpoints with the INIT, APPEND, and FINALIZE commands.

To associate an image with the specified ads account, use the media_id parameter, using the returned media_id from the POST media/upload endpoint. For videos, use the video_id parameter, using the id from the GET accounts/:account_id/videos endpoint.

Note: It is not possible to update (PUT) account media entities.

Resource URL

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

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
creative_type
required

The type of creative this media will be used as.

Type: enum

Possible values: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL
media_id
sometimes required

The identifier of an uploaded image.

This is a write-only field. In the response, the API will provide a Twitter URL for this image.

Note: Required for the banner, interstitial, and medium rectangle creative_types.

Type: long

Example: 890749735862026242
video_id
sometimes required

The identifier of a video from the GET accounts/:account_id/videos endpoint.

Note: Required for the preroll creative_type.

Type: string

Example: 13_858729103264479418

Example Request

GET https://ads-api.twitter.com/4/accounts/18ce54d4x5t/account_media?creative_type=INTERSTITIAL_LANDSCAPE_TABLET&media_id=890749735862026242

Example Response

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_id": 890749735862026242,
      "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET"
    }
  }
}

DELETE accounts/:account_id/account_media/:account_media_id

Delete the specified account media object belonging to the current account.

Resource URL

https://ads-api.twitter.com/4/accounts/:account_id/account_media/:account_media_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
account_media_id
required

A reference to the account media you are operating with in the request.

Type: string

Example: 2pnfd

Example Request

DELETE https://ads-api.twitter.com/4/accounts/18ce54d4x5t/account_media/2pnfd

Example Response

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}