Create query
Stay organized with collections
Save and categorize content based on your preferences.
The Bid Manager API Query
resource represents what you see in the UI as
a Display & Video 360 report. Run this query to generate a Report
resource. If successful, the Report
resource provides the URL where
you can download the resulting report.
This page explains how to structure and create a Query
resource.
Choose filters, dimensions, and metrics
In each Query
, provide the following Parameters
in the
params
field to refine the data that's returned in the report:
filters
limit the scope of the data. filters takes a list
of FilterPair
objects, where the
type
is a Filter enum, and the
value
is an identifying string, such as the relevant
resource ID.
groupBys
define the dimensions for the report,
represented by a list of Filter enums.
metrics
define the data populating the report,
represented by a list of Metric enums.
For more details on Query
structure, see the reference
documentation.
When choosing these values, consider your ReportType
,
that's set in the type
field. Your selected metrics and filters
values must be compatible with the report type for the report
to successfully generate.
Create a query
Once you determine the core structure of your report, you can create your query.
Here's how to create an ad hoc report consisting of data from the last seven
days:
Java
// Display name of the query to create.
String displayName = display-name;
// The report type.
String reportType = report-type;
// The advertisers and campaigns by which to filter report data.
List<String> advertiserIdFilters =
Arrays.asList(advertiser-id,...);
List<String> campaignIdFilters =
Arrays.asList(campaign-id,...);
// The dimensions and metrics for the report.
List<String> dimensions = Arrays.asList(dimension,...);
List<String> metrics = Arrays.asList(metric,...);
// Build a list of filter pairs from given IDs.
List<FilterPair> filters = new ArrayList<FilterPair>();
if (advertiserIdFilters != null) {
for (String advertiserId : advertiserIdFilters) {
filters.add(
new FilterPair().setType("FILTER_ADVERTISER").setValue(advertiserId));
}
}
if (campaignIdFilters != null) {
for (String campaignId : campaignIdFilters) {
filters.add(
new FilterPair().setType("FILTER_MEDIA_PLAN").setValue(campaignId));
}
}
// Create the query structure.
Query query = new Query();
// Build and set the metadata object.
QueryMetadata metadata = new QueryMetadata();
metadata.setTitle(displayName);
metadata.setDataRange(new DataRange().setRange("LAST_7_DAYS"));
metadata.setFormat("CSV");
query.setMetadata(metadata);
// Build the parameters object.
Parameters parameters = new Parameters();
parameters.setType(reportType);
parameters.setGroupBys(dimensions);
parameters.setFilters(filters);
parameters.setMetrics(metrics);
// Set parameters object in query.
query.setParams(parameters);
// Build and set the schedule object.
QuerySchedule schedule = new QuerySchedule();
schedule.setFrequency("ONE_TIME");
query.setSchedule(schedule);
// Create the query.
Query queryResponse = service.queries().create(query).execute();
// Log query creation.
System.out.printf("Query %s was created.%n", queryResponse.getQueryId());
Python
# Display name of the query to create.
display_name = display-name
# The report type.
report_type = report-type
# The advertisers and campaigns by which to filter report data.
filtered_advertiser_ids = [advertiser-id,...]
filtered_campaign_ids = [campaign-id,...]
# The dimensions and metrics for the report.
dimensions = [dimension,...]
metrics = [metric,...]
# Build list of FilterPair objects.
filters = []
if filtered_campaign_ids != None:
filters.extend([
{"type": "FILTER_MEDIA_PLAN", "value": id}
for id in filtered_campaign_ids
])
if filtered_advertiser_ids != None:
filters.extend([
{"type": "FILTER_ADVERTISER", "value": id}
for id in filtered_advertiser_ids
])
# Build query object.
query_obj = {
"metadata": {
"title": display_name,
"dataRange": {"range": "LAST_7_DAYS"},
"format": "CSV",
},
"params": {
"type": report_type,
"groupBys": dimensions,
"filters": filters,
"metrics": metrics,
},
"schedule": {"frequency": "ONE_TIME"}
}
# Create query object.
query_response = service.queries().create(body=query_obj).execute()
# Print new query ID.
print(f'Query {query_response["queryId"]} was created.')
PHP
// Display name of the query to create.
$displayName = display-name;
// The report type.
$reportType = report-type;
// Advertiser ID and campaign ID by which to filter data.
$advertiserIdFilters = array(advertiser-id,...);
$campaignIdFilters = array(campaign-id,...);
// The dimensions and metrics for the report.
$dimensions = array(dimension,...);
$metrics = array(metric,...);
// Build a list of filter pairs from given IDs.
$filters = array();
foreach ($advertiserIdFilters as $advertiserId) {
$filterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$filterPair->setType("FILTER_ADVERTISER");
$filterPair->setValue($advertiserId);
array_push($filters, $filterPair);
}
foreach ($campaignIdFilters as $campaignId) {
$filterPair = new Google_Service_DoubleClickBidManager_FilterPair();
$filterPair->setType("FILTER_MEDIA_PLAN");
$filterPair->setValue($campaignId);
array_push($filters, $filterPair);
}
// Create the query structure.
$query = new Google_Service_DoubleClickBidManager_Query();
// Build and set the metadata object.
$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();
$metadata->setTitle($displayName);
$metadata->setFormat("CSV");
$dataRange = new Google_Service_DoubleClickBidManager_DataRange();
$dataRange->setRange("LAST_7_DAYS");
$metadata->setDataRange($dataRange);
$query->setMetadata($metadata);
// Build and set the parameters object.
$parameters = new Google_Service_DoubleClickBidManager_Parameters();
$parameters->setType($reportType);
$parameters->setGroupBys($dimensions);
$parameters->setFilters($filters);
$parameters->setMetrics($metrics);
$query->setParams($parameters);
// Build and set the schedule object.
$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();
$schedule->setFrequency("ONE_TIME");
$query->setSchedule($schedule);
// Call the API, creating the query.
$queryResult = $this->service->queries->create($query);
printf('Query %s was created.<br>', $queryResult->getQueryId());
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-28 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eThe Bid Manager API \u003ccode\u003eQuery\u003c/code\u003e resource allows you to generate reports similar to those in the Display & Video 360 UI.\u003c/p\u003e\n"],["\u003cp\u003eReports are generated by running a \u003ccode\u003eQuery\u003c/code\u003e that defines filters, dimensions, and metrics using \u003ccode\u003eParameters\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eYou can refine report data by specifying \u003ccode\u003efilters\u003c/code\u003e, \u003ccode\u003egroupBys\u003c/code\u003e (dimensions), and \u003ccode\u003emetrics\u003c/code\u003e within the \u003ccode\u003eQuery\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eReportType\u003c/code\u003e determines which metrics and filters are compatible with your query, and it's crucial to ensure their compatibility for successful report generation.\u003c/p\u003e\n"],["\u003cp\u003eThe provided code examples demonstrate how to create an ad hoc report for the last seven days using Java, Python, and PHP.\u003c/p\u003e\n"]]],[],null,["# Create query\n\nThe Bid Manager API [`Query`](/bid-manager/reference/rest/current/queries#Query) resource represents what you see in the UI as\na Display \\& Video 360 report. Run this query to generate a [`Report`](/bid-manager/reference/rest/current/queries.reports#Report)\nresource. If successful, the [`Report`](/bid-manager/reference/rest/current/queries.reports#Report) resource provides the URL where\nyou can download the resulting report.\n\nThis page explains how to structure and create a [`Query`](/bid-manager/reference/rest/current/queries#Query) resource.\n\nChoose filters, dimensions, and metrics\n---------------------------------------\n\nIn each [`Query`](/bid-manager/reference/rest/current/queries#Query), provide the following [`Parameters`](/bid-manager/reference/rest/current/Parameters) in the\n[`params`](/bid-manager/reference/rest/current/queries#Query.FIELDS.params) field to refine the data that's returned in the report:\n\n- [`filters`](/bid-manager/reference/rest/current/Parameters#FIELDS.filters) limit the scope of the data. filters takes a list of [`FilterPair`](/bid-manager/reference/rest/current/Parameters#FilterPair) objects, where the [`type`](/bid-manager/reference/rest/current/Parameters#FilterPair.FIELDS.type) is a [Filter](/bid-manager/reference/rest/current/filters-metrics#filters) enum, and the [`value`](/bid-manager/reference/rest/current/Parameters#FilterPair.FIELDS.value) is an identifying string, such as the relevant resource ID.\n- [`groupBys`](/bid-manager/reference/rest/current/Parameters#FIELDS.group_bys) define the dimensions for the report, represented by a list of [Filter](/bid-manager/reference/rest/current/filters-metrics#filters) enums.\n- [`metrics`](/bid-manager/reference/rest/current/Parameters#FIELDS.metrics) define the data populating the report, represented by a list of [Metric](/bid-manager/reference/rest/current/filters-metrics#metrics) enums.\n\nFor more details on [`Query`](/bid-manager/reference/rest/current/queries#Query) structure, see the [reference\ndocumentation](/bid-manager/reference/rest).\n| **Tip:** If you are building a brand new report, [use the Display \\& Video 360 UI to\n| build the report structure](/bid-manager/guides/general/best-practices#build_new_reports_in_the_ui_first). In the UI, restrictions on filters, dimensions, and metrics combinations are automatically enforced.\n\nWhen choosing these values, consider your [`ReportType`](/bid-manager/reference/rest/current/Parameters#ReportType),\nthat's set in the [`type`](/bid-manager/reference/rest/current/Parameters#FIELDS.type) field. [Your selected metrics and filters\nvalues must be compatible with the report type](/bid-manager/guides/general/best-practices#use_metrics_and_filters_specific_to_the_report_type) for the report\nto successfully generate.\n\nCreate a query\n--------------\n\nOnce you determine the core structure of your report, you can create your query.\n\nHere's how to create an ad hoc report consisting of data from the last seven\ndays: \n\n### Java\n\n```java\n// Display name of the query to create.\nString displayName = display-name;\n\n// The report type.\nString reportType = report-type;\n\n// The advertisers and campaigns by which to filter report data.\nList\u003cString\u003e advertiserIdFilters =\n Arrays.asList(advertiser-id,...);\nList\u003cString\u003e campaignIdFilters =\n Arrays.asList(campaign-id,...);\n\n// The dimensions and metrics for the report.\nList\u003cString\u003e dimensions = Arrays.asList(dimension,...);\nList\u003cString\u003e metrics = Arrays.asList(metric,...);\n\n// Build a list of filter pairs from given IDs.\nList\u003cFilterPair\u003e filters = new ArrayList\u003cFilterPair\u003e();\nif (advertiserIdFilters != null) {\n for (String advertiserId : advertiserIdFilters) {\n filters.add(\n new FilterPair().setType(\"FILTER_ADVERTISER\").setValue(advertiserId));\n }\n}\nif (campaignIdFilters != null) {\n for (String campaignId : campaignIdFilters) {\n filters.add(\n new FilterPair().setType(\"FILTER_MEDIA_PLAN\").setValue(campaignId));\n }\n}\n\n// Create the query structure.\nQuery query = new Query();\n\n// Build and set the metadata object.\nQueryMetadata metadata = new QueryMetadata();\nmetadata.setTitle(displayName);\nmetadata.setDataRange(new DataRange().setRange(\"LAST_7_DAYS\"));\nmetadata.setFormat(\"CSV\");\nquery.setMetadata(metadata);\n\n// Build the parameters object.\nParameters parameters = new Parameters();\nparameters.setType(reportType);\nparameters.setGroupBys(dimensions);\nparameters.setFilters(filters);\nparameters.setMetrics(metrics);\n\n// Set parameters object in query.\nquery.setParams(parameters);\n\n// Build and set the schedule object.\nQuerySchedule schedule = new QuerySchedule();\nschedule.setFrequency(\"ONE_TIME\");\nquery.setSchedule(schedule);\n\n// Create the query.\nQuery queryResponse = service.queries().create(query).execute();\n\n// Log query creation.\nSystem.out.printf(\"Query %s was created.%n\", queryResponse.getQueryId());\n```\n\n### Python\n\n```python\n# Display name of the query to create.\ndisplay_name = display-name\n\n# The report type.\nreport_type = report-type\n\n# The advertisers and campaigns by which to filter report data.\nfiltered_advertiser_ids = [advertiser-id,...]\nfiltered_campaign_ids = [campaign-id,...]\n\n# The dimensions and metrics for the report.\ndimensions = [dimension,...]\nmetrics = [metric,...]\n\n# Build list of FilterPair objects.\nfilters = []\nif filtered_campaign_ids != None:\n filters.extend([\n {\"type\": \"FILTER_MEDIA_PLAN\", \"value\": id}\n for id in filtered_campaign_ids\n ])\nif filtered_advertiser_ids != None:\n filters.extend([\n {\"type\": \"FILTER_ADVERTISER\", \"value\": id}\n for id in filtered_advertiser_ids\n ])\n\n# Build query object.\nquery_obj = {\n \"metadata\": {\n \"title\": display_name,\n \"dataRange\": {\"range\": \"LAST_7_DAYS\"},\n \"format\": \"CSV\",\n },\n \"params\": {\n \"type\": report_type,\n \"groupBys\": dimensions,\n \"filters\": filters,\n \"metrics\": metrics,\n },\n \"schedule\": {\"frequency\": \"ONE_TIME\"}\n}\n\n# Create query object.\nquery_response = service.queries().create(body=query_obj).execute()\n\n# Print new query ID.\nprint(f'Query {query_response[\"queryId\"]} was created.')\n```\n\n### PHP\n\n```php\n// Display name of the query to create.\n$displayName = \u003cvar translate=\"no\"\u003edisplay-name\u003c/var\u003e;\n\n// The report type.\n$reportType = \u003cvar translate=\"no\"\u003ereport-type\u003c/var\u003e;\n\n // Advertiser ID and campaign ID by which to filter data.\n$advertiserIdFilters = array(\u003cvar translate=\"no\"\u003eadvertiser-id,...\u003c/var\u003e);\n$campaignIdFilters = array(\u003cvar translate=\"no\"\u003ecampaign-id,...\u003c/var\u003e);\n\n// The dimensions and metrics for the report.\n$dimensions = array(\u003cvar translate=\"no\"\u003edimension,...\u003c/var\u003e);\n$metrics = array(\u003cvar translate=\"no\"\u003emetric,...\u003c/var\u003e);\n\n// Build a list of filter pairs from given IDs.\n$filters = array();\nforeach ($advertiserIdFilters as $advertiserId) {\n $filterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n $filterPair-\u003esetType(\"FILTER_ADVERTISER\");\n $filterPair-\u003esetValue($advertiserId);\n array_push($filters, $filterPair);\n}\nforeach ($campaignIdFilters as $campaignId) {\n $filterPair = new Google_Service_DoubleClickBidManager_FilterPair();\n $filterPair-\u003esetType(\"FILTER_MEDIA_PLAN\");\n $filterPair-\u003esetValue($campaignId);\n array_push($filters, $filterPair);\n}\n\n // Create the query structure.\n$query = new Google_Service_DoubleClickBidManager_Query();\n\n // Build and set the metadata object.\n$metadata = new Google_Service_DoubleClickBidManager_QueryMetadata();\n$metadata-\u003esetTitle($displayName);\n$metadata-\u003esetFormat(\"CSV\");\n\n$dataRange = new Google_Service_DoubleClickBidManager_DataRange();\n$dataRange-\u003esetRange(\"LAST_7_DAYS\");\n$metadata-\u003esetDataRange($dataRange);\n\n$query-\u003esetMetadata($metadata);\n\n // Build and set the parameters object.\n$parameters = new Google_Service_DoubleClickBidManager_Parameters();\n$parameters-\u003esetType($reportType);\n$parameters-\u003esetGroupBys($dimensions);\n$parameters-\u003esetFilters($filters);\n$parameters-\u003esetMetrics($metrics);\n$query-\u003esetParams($parameters);\n\n // Build and set the schedule object.\n$schedule = new Google_Service_DoubleClickBidManager_QuerySchedule();\n$schedule-\u003esetFrequency(\"ONE_TIME\");\n$query-\u003esetSchedule($schedule);\n\n// Call the API, creating the query.\n$queryResult = $this-\u003eservice-\u003equeries-\u003ecreate($query);\n\nprintf('Query %s was created.\u003cbr\u003e', $queryResult-\u003egetQueryId());\n```"]]