Videos¶

GET accounts/:account_id/videos¶

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

Resource URL¶

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

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: `10` Min, Max: `1`, `50`
cursor optional	Specifies a cursor to get the next page of results. See Pagination for more information. Type: string Example: `8x7v00oow`
video_ids optional	Scope the response to just the desired videos by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided. Type: string Example: `13_875943225764098048`
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/18ce54d4x5t/videos?video_ids=13_875943225764098048

Example Response¶

{
  "data": [
    {
      "tweeted": false,
      "ready_to_tweet": true,
      "duration": 7600,
      "reasons_not_servable": [],
      "description": null,
      "preview_url": "https://video.twimg.com/amplify_video/875943225764098048/vid/1280x720/nKpW7k7QRjA3q48L.mp4",
      "id": "13_875943225764098048",
      "poster_url": "https://pbs.twimg.com/media/DCgSomqVoAAR1Nu.jpg",
      "media_key": "13_875943225764098048", // this will always be the same as `id`
      "created_at": "2017-06-17T05:08:33Z",
      "title": null,
      "aspect_ratio": "16:9",
      "updated_at": "2017-06-17T05:12:51Z",
      "deleted": false
    }
  ],
  "request": {
    "params": {
      "video_ids": [
        "13_875943225764098048"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null
}

GET accounts/:account_id/videos/:video_id¶

Retrieve a specific video associated with the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/videos/:video_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

video_id

required

A reference to video you are operating with in the request.

Type: string

Example: 13_898199863531261954

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/18ce54d4x5t/videos/13_898199863531261954

Example Response¶

{
  "data": {
    "tweeted": false,
    "ready_to_tweet": true,
    "duration": 11480,
    "reasons_not_servable": [],
    "description": "aerial",
    "preview_url": "https://video.twimg.com/amplify_video/898199863531261954/vid/1280x720/q1wB2ZSmUvOnL4dq.mp4",
    "id": "13_898199863531261954",
    "poster_url": "https://pbs.twimg.com/amplify_video_thumb/898199863531261954/img/WuQ2nSra9Bqg1EnB.jpg",
    "media_key": "13_898199863531261954",
    "created_at": "2017-08-17T15:08:29Z",
    "title": "beach",
    "aspect_ratio": "16:9",
    "updated_at": "2017-08-17T15:11:37Z",
    "deleted": false
  },
  "request": {
    "params": {
      "video_id": "13_898199863531261954",
      "account_id": "18ce54d4x5t"
    }
  }
}

POST accounts/:account_id/videos¶

Associate a video with the current account.

Videos are uploaded using the POST media/upload (chunked) endpoints with the INIT, APPEND, and FINALIZE commands. They are then associated with an ads account using the POST accounts/:account_id/videos endpoint. For a short guide on promoted video in the Ads API, please see our Promoted Video Overview.

Videos uploaded to the API are not eligible for Tweeting or use in video cards until the video has been successfully processed. Processing time is generally just a few minutes, but does vary. Once a video has been processed, video object values such as duration, ready_to_tweet, and preview_url will become available. For a full list of reasons why a given video is not servable, please see our enums page.

Resource URL¶

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

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`
video_media_id required	The `media_id` for the uploaded video content. Please see POST media/upload (chunked) for more information about uploading videos. Type: long Example: `858201340161343488`
description optional	A string value to populate the video description with. This value is not user-facing and is only utilized for identification purposes in the GET accounts/:account_id/videos endpoint and the Twitter Ads UI video library. Type: string Example: `creating your first campaign`
poster_image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: `858201804344934400`
title optional	A string value to populate the video title with. This value is not user-facing and is only utilized for identification purposes in the GET accounts/:account_id/videos endpoint and the Twitter Ads UI video library. Type: string Example: `playbook`

Example Request¶

POST https://ads-api.twitter.com/3/accounts/18ce54d4x5t/videos?video_media_id=858201340161343488&poster_image_media_id=858201804344934400

Example Response¶

{
  "data": {
    "id": "13_858201340161343488"
  },
  "request": {
    "params": {
      "video_media_id": 858201340161343488,
      "poster_image_media_id": 858201804344934400,
      "account_id": "18ce54d4x5t"
    }
  }
}

PUT accounts/:account_id/videos/:video_id¶

Update the specified video object belonging to the current account.

Resource URL¶

https://ads-api.twitter.com/3/accounts/:account_id/videos/:video_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`
video_id required	A reference to the video you are operating with in the request. Type: string Example: `13_858201340161343488`
description optional	A string value to populate the video description with. This value is not user-facing and is only utilized for identification purposes in the GET accounts/:account_id/videos endpoint and the Twitter Ads UI video library. Type: string Example: `creating your first campaign`
poster_image_media_id optional	Specify a poster image for the video using the `media_id` of an uploaded image. If not specified, the first frame will be used. This is a write-only field. In the response, the API will provide a Twitter URL for this image. Type: long Example: `858538124313378818`
title optional	A string value to populate the video title with. This value is not user-facing and is only utilized for identification purposes in the GET accounts/:account_id/videos endpoint and the Twitter Ads UI video library. Type: string Example: `playbook`

Example Request¶

PUT https://ads-api.twitter.com/3/accounts/18ce54d4x5t/videos/13_858201340161343488?poster_image_media_id=858538124313378818

Example Response¶

{
  "data": {
    "tweeted": false,
    "ready_to_tweet": false,
    "duration": null,
    "reasons_not_servable": [],
    "description": "in the ocean",
    "preview_url": null,
    "id": "13_858201340161343488",
    "poster_url": null,
    "media_key": "13_858201340161343488", // this will always be the same as `id`
    "created_at": "2017-04-29T06:08:38Z",
    "title": "dolphins",
    "aspect_ratio": null,
    "updated_at": "2017-04-30T04:29:14Z",
    "deleted": false
  },
  "request": {
    "params": {
      "video_id": "13_858201340161343488",
      "account_id": "18ce54d4x5t",
      "poster_image_media_id": 858538124313378818
    }
  }
}

DELETE accounts/:account_id/videos/:video_id¶

Delete the specified video belonging to the current ads account.

Resource URL¶

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

Parameters¶

Name Description

account_id

required

Type: string

Example: 18ce54d4x5t

video_id

required

A reference to the video you are operating with in the request.

Type: string

Example: 13_898199863531261954

Example Request¶

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/videos/13_898199863531261954

Example Response¶

{
  "data": {
    "tweeted": false,
    "ready_to_tweet": false,
    "duration": 11480,
    "reasons_not_servable": [],
    "description": "aerial",
    "preview_url": "https://video.twimg.com/amplify_video/898199863531261954/vid/1280x720/q1wB2ZSmUvOnL4dq.mp4",
    "id": "13_898199863531261954",
    "poster_url": "https://pbs.twimg.com/amplify_video_thumb/898199863531261954/img/WuQ2nSra9Bqg1EnB.jpg",
    "media_key": "13_898199863531261954",
    "created_at": "2017-08-17T15:08:29Z",
    "title": "beach",
    "aspect_ratio": "16:9",
    "updated_at": "2017-08-17T15:11:37Z",
    "deleted": true
  },
  "request": {
    "params": {
      "video_id": "13_898199863531261954",
      "account_id": "18ce54d4x5t"
    }
  }
}

Creatives

Videos¶

GET accounts/:account_id/videos¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

GET accounts/:account_id/videos/:video_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

POST accounts/:account_id/videos¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

PUT accounts/:account_id/videos/:video_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶

DELETE accounts/:account_id/videos/:video_id¶

Resource URL¶

Parameters¶

Example Request¶

Example Response¶