Skip to content
Ads API •References / Ads / Get Ads

Get Ads

Returns a list of all available ads.

Request

POST
/ads
  • organization_ids
    array of strings
  • ad_account_ids
    array of strings
  • ad_ids
    array of strings
  • limit
    integer [int32]
    Example: 2
  • offset
    integer [int32]
    Example: 0

Response

    • advertiser_id
      string [uuid]

      The unique ID returned when a new advertiser is created.

      • audio_asset_id
        string [uuid]
        Required

        The ID provided back when an upload url is requested. Note this does not mean it's processed successfully; you will need to check the status for that. Currently deprecated and renamed to asset_id.

        Example: "2f5488b7-0a48-4751-b3b8-701df2d8cd90"
      • asset_id
        string [uuid]
        Required

        The ID provided back when an upload url is requested. Note this does not mean it's processed successfully; you will need to check the status for that.

        Example: "2f5488b7-0a48-4751-b3b8-701df2d8cd90"
      • audio_asset_url
        string [uri]

        The URL that returns an audio asset. Deprecated; renamed to asset_url.

        Example: "www.spotify.com"
      • asset_url
        string [uri]

        The URL that returns an asset.

        Example: "www.spotify.com"
      • companion_asset_id
        string [uuid]
        Required

        The ID provided back when an companion image upload url is requested. Note this does not mean its Processed successfully, you will need to check the status for that* bbbv , cv.

      • companion_asset_url
        string [uri]

        The URL that returns a companion image.

        Example: "www.spotify.com"
    • landing_page_domain
      string [uri]

      URL the campaign will direct to

    • clickthrough_url
      string [uri]

      The link to the ads desired landing page activated by a button labelled CTA below and also the cover art image.

    • created
      string [date-time]

      Date the ad was created Time is in ISO-8601 format

    • id
      string [uuid]

      ID for the actual ad ad that will be displayed to the user. It is a container for assets and metadata for the ad. It contains asset IDs which are generated via the asset endpoint.

    • name
      string

      Name given to identify your ad.

    • status
      string [ad-status]
      Allowed values: "ACTIVE", "PENDING", "PENDING_USER_APPROVAL", "PENDING_ADMIN_APPROVAL", "APPROVED", "REJECTED", "ARCHIVED", "UNRECOGNIZED"Example: "ACTIVE"
    • reject_reason
      string
    • brand_name
      string
    • tagline
      string
      • measurement_partner
        string [measurement-partner]
        Allowed values: "IAS"Example: "IAS"
      • url
        string
    • version
      integer [int64]

      When a campaign is created or updated, it is assigned a new version.

Response sample

{  "ads": [    {      "advertiser_id": "za66a2eb-35cf-46a4-8d2e-0j95dfc133r4",      "assets": {        "audio_asset_id": "2f5488b7-0a48-4751-b3b8-701df2d8cd90",        "asset_id": "2f5488b7-0a48-4751-b3b8-701df2d8cd90",        "audio_asset_url": "www.spotify.com",        "asset_url": "www.spotify.com",        "companion_asset_id": "2g5488b7-0a48-4751-b3b8-701df2d8cd91",        "companion_asset_url": "www.spotify.com"      },      "landing_page_domain": "www.spotify.com",      "clickthrough_url": "www.spotify.com",      "created": "2022-02-07T21:00:00Z",      "id": "pa66a2eb-35cf-46a4-8d2e-0j95dfc133r7",      "name": "Spotify Discover Weekly feature ad",      "status": "ACTIVE",      "reject_reason": "Rejected reason",      "brand_name": "This is a brand",      "tagline": "This is a tagline",      "third_party_viewability_tracking": {        "measurement_partner": "IAS",        "url": "www.spotify.com"      },      "version": 1    },    {      "advertiser_id": "za66a2eb-35cf-46a4-8d2e-0j95dfc133r4",      "assets": {        "audio_asset_id": "2f5488b7-0a48-4751-b3b8-701df2d8cd90",        "asset_id": "2f5488b7-0a48-4751-b3b8-701df2d8cd90",        "audio_asset_url": "www.spotify.com",        "asset_url": "www.spotify.com",        "companion_asset_id": "2g5488b7-0a48-4751-b3b8-701df2d8cd91",        "companion_asset_url": "www.spotify.com"      },      "landing_page_domain": "www.spotify.com",      "clickthrough_url": "www.spotify.com",      "created": "2022-02-07T21:00:00Z",      "id": "pa66a2eb-35cf-46a4-8d2e-0j95dfc133r7",      "name": "Spotify Discover Weekly feature ad",      "status": "ACTIVE",      "reject_reason": "Rejected reason",      "brand_name": "This is a brand",      "tagline": "This is a tagline",      "third_party_viewability_tracking": {        "measurement_partner": "IAS",        "url": "www.spotify.com"      },      "version": 1    }  ]}