Campaign Management

Media Creatives

GET accounts/:account_id/media_creatives

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

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/media_creatives

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

Scope the response to just the media creatives associated with the specified campaign.

Type: string

Example: 8gdx6
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_id
optional

Scope the response to just the media creatives associated with the specified line item.

Type: string

Example: 8v7jo
media_creative_ids
optional

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

Type: string

Example: 1bzq3
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/3/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3

Example Response

{
  "request": {
    "params": {
      "media_creative_ids": [
        "1bzq3"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v7jo",
      "landing_url": null,
      "serving_status": "ACTIVE",
      "id": "1bzq3",
      "created_at": "2017-07-05T06:00:42Z",
      "account_media_id": "10miy",
      "updated_at": "2017-07-05T06:00:43Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/media_creatives/:media_creative_id

Retrieves details for a specific media creative associated with the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/media_creatives/:media_creative_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
media_creative_id
required

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

Type: string

Example: 43853bhii885
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/3/accounts/abc1/media_creatives/yav

Example Response

{
  "data": {
    "line_item_id": "3gtpw",
    "landing_url": "http://www.google.com",
    "serving_status": "ACTIVE",
    "id": "yav",
    "created_at": "2015-10-26T22:27:38Z",
    "account_media_id": "7ng",
    "updated_at": "2015-11-04T07:24:27Z",
    "approval_status": "ACCEPTED",
    "deleted": false
  },
  "request": {
    "params": {
      "media_creative_id": "yav",
      "account_id": "abc1"
    }
  }
}

POST accounts/:account_id/media_creatives

Associate an account media object with the specified line item.

Use this endpoint to promote in-stream ads (when the account media creative_type is PREROLL) or image ads (such as BANNER or INTERSTITIAL) on the Twitter Audience Platform.

Prequisite: Use the POST accounts/:account_id/account_media endpoint to set up the media asset.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/media_creatives

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 entity you are operating with in the request.

Type: string

Example: 10miy
line_item_id
required

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

Type: string

Example: 8v7jo
landing_url
optional

The URL of the website to direct a user to.

Type: string

Example: https://blog.twitter.com/

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy

Example Response

{
  "data": {
    "line_item_id": "8v7jo",
    "landing_url": null,
    "serving_status": "ACTIVE",
    "id": "1bzq3",
    "created_at": "2017-07-05T06:00:42Z",
    "account_media_id": "10miy",
    "updated_at": "2017-07-05T06:00:42Z",
    "approval_status": "ACCEPTED",
    "deleted": false
  }
}

DELETE accounts/:account_id/media_creatives/:media_creative_id

Delete the specified media creative belonging to the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/media_creatives/:media_creative_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
media_creative_id
required

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

Type: string

Example: 1bzq3

Example Request

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

{
  "data": {
    "line_item_id": "8v7jo",
    "landing_url": "https://dev.twitter.com",
    "serving_status": "ACTIVE",
    "id": "1bzq3",
    "created_at": "2017-07-05T06:00:42Z",
    "account_media_id": "10miy",
    "updated_at": "2017-08-30T06:01:11Z",
    "approval_status": "ACCEPTED",
    "deleted": true
  },
  "request": {
    "params": {
      "media_creative_id": "1bzq3",
      "account_id": "18ce54d4x5t"
    }
  }
}