Method: ads.list

  • This webpage describes how to retrieve a list of ads, potentially filtered, supporting paging.

  • The HTTP request uses a GET method with a URL specifying the user profile ID.

  • The list of ads can be filtered and sorted using various query parameters such as IDs, active status, campaign IDs, and more.

  • The request body for retrieving the list of ads must be empty.

  • The successful response body contains a list of ad objects, a kind identifier, and a next page token for pagination.

  • This operation requires the https://www.googleapis.com/auth/dfatrafficking OAuth scope for authorization.

Retrieves a list of ads, possibly filtered. This method supports paging.

HTTP request

GET https://dfareporting.googleapis.com/dfareporting/v4/userprofiles/{profileId}/ads

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
profileId

string (int64 format)

User profile ID associated with this request.

Query parameters

Parameters
ids[]

string (int64 format)

Select only ads with these IDs.
active

boolean

Select only active ads.
archived

boolean

Select only archived ads.
campaignIds[]

string (int64 format)

Select only ads with these campaign IDs.
advertiserId

string (int64 format)

Select only ads with this advertiser ID.
type[]

enum (AdServingType)

Select only ads with these types.
dynamicClickTracker

boolean

Select only dynamic click trackers. Applicable when

type

is

AD_SERVING_CLICK_TRACKER

. If true, select dynamic click trackers. If false, select static click trackers. Leave unset to select both.
compatibility

enum (Compatibility)

Select default ads with the specified compatibility. Applicable when

type

is

AD_SERVING_DEFAULT_AD

.

DISPLAY

and

DISPLAY_INTERSTITIAL

refer to rendering either on desktop or on mobile devices for regular or interstitial ads, respectively.

APP

and

APP_INTERSTITIAL

are for rendering in mobile apps.

IN_STREAM_VIDEO

refers to rendering an in-stream video ads developed with the VAST standard.
sizeIds[]

string (int64 format)

Select only ads with these size IDs.
landingPageIds[]

string (int64 format)

Select only ads with these landing page IDs.
maxResults

integer

Maximum number of results to return.
creativeIds[]

string (int64 format)

Select only ads with these creative IDs assigned.
placementIds[]

string (int64 format)

Select only ads with these placement IDs assigned.
remarketingListIds[]

string (int64 format)

Select only ads whose list targeting expression use these remarketing list IDs.
audienceSegmentIds[]

string (int64 format)

Select only ads with these audience segment IDs.
overriddenEventTagId

string (int64 format)

Select only ads with this event tag override ID.
sslRequired

boolean

Select only ads that require SSL.
sslCompliant

boolean

Select only ads that are SSL-compliant.
creativeOptimizationConfigurationIds[]

string (int64 format)

Select only ads with these creative optimization configuration IDs.
pageToken

string

Value of the

nextPageToken

from the previous result page.
searchString

string

Allows searching for objects by name or ID. Wildcards (

*

) are allowed. For example,

"ad*2015"

will return objects with names like

"ad June 2015"

,

"ad April 2015"

, or simply

"ad 2015"

. Most of the searches also add wildcards implicitly at the start and the end of the search string. For example, a search string of

"ad"

will match objects with name

"my ad"

,

"ad 2015"

, or simply

"ad"

.
sortField

enum (SortField)

Field by which to sort the list.
sortOrder

enum (SortOrder)

Order of sorted results.

Request body

The request body must be empty.

Response body

Ad ads.list Response

If successful, the response body contains data with the following structure:

JSON representation 
{
  "kind": string,
  "nextPageToken": string,
  "ads": [
    {
      object (Ad)
    }
  ]
}
Fields
kind

string

Identifies what kind of resource this is. Value: the fixed string

"dfareporting#adsListResponse"

.
nextPageToken

string

Pagination token to be used for the next list operation.
ads[]

object (Ad)

Ad collection.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/dfatrafficking