Ads API •References / ads / Get Ad Drafts

Get Ad Drafts

Get a list of draft ads for the ad account.

Request

ad_account_idstring [uuid]
Required
A unique identifier for an Ad Account.
Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
limitinteger
Limit or page size for a given response.
Default: limit=50Range: 1 - 50Example: limit=50
offsetinteger
Starting position of the next record to assist in data pagination.
Default: offset=0Example: offset=0
ad_set_idsarray of strings
A list of Ad Set IDs to fetch Ads for only the given subset of Ad Sets
A unique identifier for the entity.
Example: ad_set_ids=ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
statusesarray of strings
Unique items
The set of enums that will be used to filter Ad by statuses. The filter will match any Ad that has one of the given statuses.
Status of the ad.
Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING", "PENDING_APPROVAL", "REJECTED", "UNRECOGNIZED"Example: statuses=PENDING

Response

Ad Drafts response.

- page_sizeinteger [int32]
- total_resultsinteger [int32]
- offsetinteger [int32]
- current_pageinteger [int32]
- statusstring
  Status of the ad.
  Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "PENDING", "PENDING_APPROVAL", "REJECTED", "UNRECOGNIZED"Example: "PENDING"
- draft_hierarchy_versioninteger
  Read only
  The version of the draft hierarchy. Required when publishing the campaign draft.
  Minimum value: 1Example: 1
- idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- created_atstring [date-time]
  Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
  Example: "2026-01-23T04:56:07Z"
- updated_atstring [date-time]
  Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
  Example: "2026-01-23T04:56:07Z"
- ad_set_idstring [uuid]
  Required
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- namestring
  Name given to identify the ad draft.
  Example: "New Ad Draft"
- advertiser_namestring
  Name of the advertiser for the ad draft.
  Example: "Heart Dance Recordings"
- Assets for the ad.
  asset_idstring [uuid]
  Required
  A unique identifier for an AUDIO, VIDEO or IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  companion_asset_idstring [uuid]
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  logo_asset_idstring [uuid]
  Required
  A unique identifier for an IMAGE asset.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  canvas_asset_idstring [uuid]
  A unique identifier for an IMAGE or VIDEO asset with 9:16 aspect ratio.
  Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- asset_formatstring
  Format of the asset.
  Allowed values: "AUDIO", "VIDEO", "IMAGE", "CATALOG"Example: "AUDIO"
- taglinestring
  Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
  Example: "Good Food for Good Dogs"
- Array maximum length: 11
  Third party viewability tracking via partner and url
  measurement_partnerstring
  Name of the third-party measurement partner.
  Allowed values: "IAS", "DCM", "UNSET"Example: "IAS"
  urlstring
  Third-party tracking URL.
  Example: "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"
- The metadata for the behavior of the call-to-action button.
  keystring
  The identifier used for the call-to-action button. This will be translated using the locale.
  Allowed values: "APPLY_NOW", "BOOK_NOW", "BUY_NOW", "BUY_TICKETS", "CLICK_NOW", "DOWNLOAD", "FIND_STORES", "GET_COUPON", "GET_INFO", "LEARN_MORE", "LISTEN_NOW", "MORE_INFO", "ORDER_NOW", "PRE_SAVE", "SAVE_NOW", "SHARE", "SHOP_NOW", "SIGN_UP", "VISIT_PROFILE", "VISIT_SITE", "WATCH_NOW"Example: "LEARN_MORE"
  languagestring
  The language which the ad is presented.
  Allowed values: "ARABIC", "ARABIC_EGYPT", "BULGARIAN", "CHINESE", "CHINESE_HK", "CHINESE_TAIWAN", "CROATIAN", "CZECH", "DANISH", "DUTCH", "ENGLISH", "FINNISH", "FRENCH", "FRENCH_CANADA", "GERMAN", "GREEK", "HEBREW", "HUNGARIAN", "INDONESIAN", "ITALIAN", "JAPANESE", "KOREAN", "NORWEGIAN", "POLISH", "PORTUGUESE", "PORTUGUESE_PORTUGAL", "ROMANIAN", "RUSSIAN", "SLOVAK", "SPANISH", "SPANISH_ARGENTINA", "SPANISH_LATAM_CARIBBEAN", "SPANISH_MEXICO", "SWEDISH", "THAI", "TURKISH", "UKRAINIAN", "VIETNAMESE"Example: "ENGLISH"
  clickthrough_urlstring
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
- placementsarray of strings
  Placement of the ad.
  Allowed values: "MUSIC", "PODCAST"Example: "MUSIC"
- Catalog of things to be placed in a carousel type ad. Ad Set asset_format must be set to CATALOG.
  idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  namestring
  Name given to identify your catalog.
  Example: "Holiday Deals"
  Item within a catalog
  idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  asset_idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  Metadata associated with attached asset_id. Only present in response.
  asset_typestring
  The type of asset.
  Allowed values: "AUDIO", "IMAGE", "VIDEO"Example: "IMAGE"
  asset_namestring
  Name of attached assetId.
  Example: "File name"
  asset_urlstring [uri]
  URL associated with attached asset_id.
  Example: "https://example.com/asset_id"
  skustring
  Client defined product ID. Must be unique to a catalog.
  Example: "SKU-7415695"
  positioninteger
  Required
  Preferred ordering to display the catalog items in ads.
  Example: 3
  clickthrough_urlstring [uri]
  The link to the ads desired landing page.
  Example: "https://www.spotify.com"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_pricestring
  Displayable localized price. Only present in response.
  Example: "$19.99 USD"
  microinteger [int64]
  Price multiplied by x10 to the 6th power. Ex: cost of $250, would be a cost_micro of 250000000.
  Example: 250000000
  currency_codestring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
  display_sale_pricestring
  Displayable localized sale price. Only present in response.
  Example: "$14.99 USD"
  taglinestring
  Tagline to give listeners more context about your company or product. This will be displayed in the CTA card leavebehind.
  Pattern: ^\S.*\S$Length between 2 and 40Example: "Good Food for Good Dogs"
- dv_client_codestring
  DoubleVerify client code.
  Example: "2097467"
- weightinteger [int32]
  The weight of the ad.
  Range: 1 - 100Example: 10

Response sample

{  "paging": {    "page_size": 0,    "total_results": 0,    "offset": 0,    "current_page": 0  },  "ad_drafts": [    {      "status": "PENDING",      "draft_hierarchy_version": 1,      "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "created_at": "2026-01-23T04:56:07Z",      "updated_at": "2026-01-23T04:56:07Z",      "ad_set_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "name": "New Ad Draft",      "advertiser_name": "Heart Dance Recordings",      "assets": {        "asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "companion_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "logo_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "canvas_asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"      },      "asset_format": "AUDIO",      "tagline": "Good Food for Good Dogs",      "third_party_tracking": [        {          "measurement_partner": "IAS",          "url": "https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email"        }      ],      "call_to_action": {        "key": "LEARN_MORE",        "language": "ENGLISH",        "clickthrough_url": "https://www.spotify.com"      },      "placements": ["MUSIC"],      "catalog": {        "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",        "name": "Holiday Deals",        "catalog_items": [          {            "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",            "asset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",            "asset": {              "asset_type": "IMAGE",              "asset_name": "File name",              "asset_url": "https://example.com/asset_id"            },            "sku": "SKU-7415695",            "position": 3,            "clickthrough_url": "https://www.spotify.com",            "price": {              "micro": 250000000,              "currency_code": "USD"            },            "display_price": "$19.99 USD",            "sale_price": {              "micro": 250000000,              "currency_code": "USD"            },            "display_sale_price": "$14.99 USD",            "tagline": "Good Food for Good Dogs"          }        ]      },      "dv_client_code": "2097467",      "weight": 10    }  ]}