---
title: "Submit an aggregate query job"
method: POST
path: "/v1/batch-query"
tags: ["Aggregate Queries"]
---

# Submit an aggregate query job

`POST /v1/batch-query`

Submits an AQuA job that contains an aggregated list of ZOQL and Export ZOQL queries.

## Headers

- `Idempotency-Key` string
- `Accept-Encoding` string
- `Content-Encoding` string
- `Zuora-Entity-Ids` string
- `Zuora-Org-Ids` string
- `Zuora-Track-Id` string
- `Zuora-Version` string

## Request body

- SubmitBatchQueryRequest
  - `dateTimeUtc` boolean — When using WSDL 69 and later you can ensure that the exported output of dateTime records are rendered according to ISO-8601 generic UTC form by setting `dateTimeUtc` to `true`. When `dateTimeUtc` is set to `true`, exports of dateTime data types will be rendered in the following generic format: `YYYY-MM-DDThh:mm:ss-hhmm` or `YYYY-MM-DDThh:mm:ss+hhmm`. **Note**: Regardless of what batchType query is used (`zoql` or `zoqlexport`), the query response output for datetime data types can be standardized by setting dateTimeUtc to `true`. When `true`, the results will display datetime types with the format: YYYY-MM-DDThh:mm:ss+/-hhmm.
  - `format` 'csv' | 'zip' | 'gzip' — The format of the query. The default value is `csv`.
  - `incrementalTime` string, dateTime — Allows you to override the time from which a Stateful AQuA job incrementally retrieves records that have been created or modified, using the `incrementalTime` parameter. For example, if you set `incrementalTime` = `2015-01-21 10:30:01`, AQuA will retrieve records that have created or modified beginning at 10:30:01. If this parameter is not set, AQuA continues to use the Start Time of the last AQuA session to retrieve records incrementally. The time zone of `incrementalTime` depends on which Zuora data center you use. For US Data Center customers, the time zone of `incrementalTime` is Pacific Time. For EU Data Center customers, the time zone of `incrementalTime` is UTC. If the time zone of your system is different from the time zone of `incrementalTime`, you will need to convert to the appropriate time zone before setting `incrementalTime`. **Note**: This field can only be used in Stateful AQuA mode.
  - `name` string — The name of the job. 32 character limit.
  - `notifyUrl` string — If URL is provided, the AQuA job will call this `notifyUrl` once the job has completed. The value of `notifyUrl` needs to have `${JOBID}` and `${STATUS}` placeholders. These placeholders will be replaced by the actual job ID and status when returned in the response. Status will be `Completed` after the AQuA job is done. If you submit an AQuA query with `notifyUrl` specified, the value of `notifyUrl` will be ignored if your organization has already <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/Callout_Notification_for_Completed_AQuA_Jobs" target="_blank">configured a callout notification through the Zuora user interface</a>.
  - `nullReplacement` string — The string used to represent null values in the query results. If you do not set this parameter, null values are represented by the empty string in the query results.
  - `offset` integer — This field specifies the time offset for AQuA queries in stateful mode. It is an integer in the range 0 to 3,600 seconds. For example, if you set this field to 600 seconds and you post a query in stateful mode at 2:00 AM, it will query against data created or updated between the completion time of the previous query and 1:50 AM. The value of this field will override the value you configured in **Settings** > **Administration** > **AQuA API Stateful Mode Time Offset**.
  - `partner` string — The partner field indicates the unique ID of a data integration partner. The dropdown list of this field displays partner IDs for the past thirty days. It must be used together with "project" field to uniquely identify a data integration target. For example, if a continuous AQuA session is to retrieve data incrementally for a Salesforce.com Org 00170000011K3Ub, you can use partner as "Salesforce", and "project" as "00170000011K3Ub." This field is required only if you are using AQuA in stateful mode. Otherwise, if you are using AQuA in stateless mode, partner field can be null. **Note**: Zuora highly recommends you use the stateless mode instead of the stateful mode to extract bulk data. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/Bulk_data__extraction_from_Zuora_using_AQuA" target="_blank">Bulk data extraction from Zuora using AQuA</a> for best practices. **Note**: Submit a request at <a href="http://support.zuora.com" target="_blank">Zuora Global Support</a> to obtain a partner ID.
  - `project` string — The project field contains the unique ID of a data integration project for a particular partner. The dropdown list of this field displays project IDs for the past thirty days. This field must be used together with partner field to uniquely identify a data integration target. This field is required only if you are using AQuA in stateful mode. Otherwise, if you are using AQuA in stateless mode, partner field can be null.
  - `queries` BatchQuery[] — A JSON array object that contains a list of batch objects.
    - `apiVersion` string — The API version for the query. If an API version is not specified, the latest version is used by default. Using the latest WSDL version is most useful for reporting use cases. For integration purposes, specify the WSDL version to ensure consistent query behavior, that is, what is supported and included in the response returned by the API. **Note**: As of API version 69 and later, Zuora changed the format of certain fields. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/G_SOAP_API/AB_Getting_started_with_the__SOAP_API/C_Date_Field_Changes_in_the_SOAP_API" target="_blank">Date Field Changes in the SOAP API</a> for more information and a list of affected fields.
    - `convertToCurrencies` string — The currencies that you want to convert transaction amounts into. You can specify any number of currencies. Specify the currencies using their <a href="https://knowledgecenter.zuora.com/Quick_References/Country%2C_State%2C_and_Province_Codes/D_Currencies_and_Their_3-Letter_Codes" target="_blank">ISO currency codes</a> and separate each currency with a comma, for example, "EUR,GBP,JPY". See <a href="https://knowledgecenter.zuora.com/Zuora_Collect/Zuora_Finance/D_Finance_Settings/F_Foreign_Currency_Conversion/Foreign_Currency_Conversion_for_Data_Source_Exports#Creating_the_Data_Source_Export_Using_the_AQuA_API" target="_blank">Convert Transaction Amounts Into Any Currency</a> for more information and examples. To use this field, you must have <a href="https://knowledgecenter.zuora.com/Zuora_Collect/Zuora_Finance/D_Finance_Settings/F_Foreign_Currency_Conversion" target="_blank">Foreign Currency Conversion</a> enabled and you must be using API version 78 or later.
    - `deleted` object[] — This field indicates that the AQuA incremental load will retrieve deleted records. If you want to export deleted data, this field is required. **Note**: AQuA API is subject to Zuora Data Retention Policy. The retention period of deleted data is 30 days. You can only retrieve deleted data for 30 days through AQuA.
      - `column` string — Name of the Column in the extracted file that points to the deleted records.
      - `format` string — Can be set to either `Numeric` or `Boolean`. If set to `Numeric`, deleted records are marked as `1`. If set to `Boolean`, deleted records are marked as `true`.
    - `name` string — The query name that can uniquely identify the query in this API request.
    - `query` string — A valid ZOQL query or Export ZOQL query statement.
    - `type` 'zoql' | 'zoqlexport' — The query type.
  - `sourceData` 'LIVE' — Specify the source this aggregate query runs against: * `LIVE` represents the live transactional databases at Zuora (Data Query Live). If this field is not specified, the default value `LIVE` will be used.
  - `useQueryLabels` boolean — When this optional flag is set to `true` the request will use object and field API names for the CSV header output instead of the field labels. Data integration projects should set `useQueryLabels` to `true` so that API names remain the same. By default `useQueryLabels` is `false`, so that output CSV headers display the more user-friendly object and field labels.
  - `version` number, float — The API version you want to use. The supported versions are as follows: - `1.1`. It supports both modes - `1.0`. Default. It supports stateless modes only. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/BA_Stateless_and_Stateful_Modes" target="_blank">Stateless and stateful modes</a> for more information.

## Response `200`

OK

- SubmitBatchQueryResponse
  - `batches` BatchesQueries[] — A JSON array object that contains a list of batch objects.
    - `apiVersion` string — The API version for the query. If an API version is not specified, the latest version is used by default. Using the latest WSDL version is most useful for reporting use cases. For integration purposes, specify the WSDL version to ensure consistent query behavior, that is, what is supported and included in the response returned by the API. **Note**: As of API version 69 and later, Zuora changed the format of certain fields. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/G_SOAP_API/AB_Getting_started_with_the__SOAP_API/C_Date_Field_Changes_in_the_SOAP_API" target="_blank">Date Field Changes in the SOAP API</a> for more information and a list of affected fields.
    - `batchId` string — A 32-character ID of the query batch.
    - `batchType` 'zoql' | 'zoqlexport' — The kind of batch job being submitted.
    - `deleted` object[] — This field indicates that the AQuA incremental load will retrieve deleted records. **Note**: AQuA API is subject to Zuora Data Retention Policy. The retention period of deleted data is 30 days. You can only retrieve deleted data for 30 days through AQuA.
      - `column` string — Name of the Column in the extracted file that points to the deleted records.
      - `format` string — Can be set to either `Numeric` or `Boolean`. If set to `Numeric`, deleted records are marked as `1`. If set to `Boolean`, deleted records are marked as `true`.
    - `full` boolean — This field indicates a full or incremental load. `True` = Full and `False` = Incremental.
    - `name` string — Name of the query supplied in the request.
    - `query` string — The requested query string.
    - `recordCount` string — The number of records included in the query output file.
    - `status` 'submitted' | 'pending' | 'executing' | 'completed' | 'aborted' | 'deleted_notallowed' — The status of the query task: - submitted: The query was submitted to the query executor for processing. - pending: The query was waiting for being processed. - executing: The query is being processed. - completed: The query was successfully executed. - aborted: The query execution failed. - deleted_notallowed: The query execution failed because objects included in the query do not support the querying of deleted records.
  - `encrypted` 'pgp' | 'none' — If enabled, you must supply the formatting (zip or unzip) first and decrypt it to get the actual contents.
  - `format` 'csv' | 'zip' | 'gzip' — The format of the query. The default value is `csv`.
  - `id` string — The job ID created for the AQuA API request. The job ID can be used for querying for the query status. The ID exists only if the JSON request can be parsed and validated successfully. Otherwise, the job ID is null.
  - `incrementalTime` string, dateTime — Allows you to override the time from which a Stateful AQuA job incrementally retrieves records that have been created or modified, using the `incrementalTime` parameter. For example, if you set `incrementalTime` = `2015-01-21 10:30:01`, AQuA will retrieve records that have created or modified beginning at 10:30:01. If this parameter is not set, AQuA continues to use the Start Time of the last AQuA session to retrieve records incrementally. The time zone of `incrementalTime` depends on which Zuora data center you use. For US Data Center customers, the time zone of `incrementalTime` is Pacific Time. For EU Data Center customers, the time zone of `incrementalTime` is UTC. If the time zone of your system is different from the time zone of `incrementalTime`, you will need to convert to the appropriate time zone before setting `incrementalTime`. **Note**: This field can only be used in Stateful AQuA mode.
  - `name` string — The name of the job. 32 character limit.
  - `notifyUrl` string — If URL is provided, the AQuA job will call this `notifyUrl` once the job has completed. The value of `notifyUrl` needs to have `${JOBID}` and `${STATUS}` placeholders. These placeholders will be replaced by the actual job ID and status when returned in the response. Status will be `Completed` after the AQuA job is done. If you submit an AQuA query with `notifyUrl` specified, the value of `notifyUrl` will be ignored if your organization has already <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/Callout_Notification_for_Completed_AQuA_Jobs" target="_blank">configured a callout notification through the Zuora user interface</a>.
  - `offset` integer — This field specifies the time offset for AQuA queries in stateful mode. It is an integer in the range 0 to 3,600 seconds. For example, if you set this field to 600 seconds and you post a query in stateful mode at 2:00 AM, it will query against data created or updated between the completion time of the previous query and 1:50 AM. The value of this field will override the value you configured in **Settings** > **Administration** > **AQuA API Stateful Mode Time Offset**.
  - `partner` string — The partner field indicates the unique ID of a data integration partner. The dropdown list of this field displays partner IDs for the past thirty days. It must be used together with "project" field to uniquely identify a data integration target. For example, if a continuous AQuA session is to retrieve data incrementally for a Salesforce.com Org 00170000011K3Ub, you can use partner as "Salesforce", and "project" as "00170000011K3Ub." This field is required only if you are using AQuA in stateful mode. Otherwise, if you are using AQuA in stateless mode, partner field can be null. **Note**: Zuora highly recommends you use the stateless mode instead of the stateful mode to extract bulk data. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/Bulk_data__extraction_from_Zuora_using_AQuA" target="_blank">Bulk data extraction from Zuora using AQuA</a> for best practices. **Note**: Submit a request at <a href="http://support.zuora.com" target="_blank">Zuora Global Support</a> to obtain a partner ID.
  - `project` string — The project field contains the unique ID of a data integration project for a particular partner. The dropdown list of this field displays project IDs for the past thirty days. This field must be used together with partner field to uniquely identify a data integration target. This field is required only if you are using AQuA in stateful mode. Otherwise, if you are using AQuA in stateless mode, partner field can be null.
  - `sourceData` string — Indicates the source this aggregate query runs against: * `LIVE` represents the live transactional databases at Zuora (Data Query Live).
  - `status` 'submitted' | 'executing' | 'completed' | 'error' | 'aborted' | 'cancelled' — The status of the AQuA job: - submitted: The AQuA job was submitted to the query executor for processing. - executing: The AQuA job is being processed. - completed: The AQuA job was successfully executed. - error: The AQuA job was not processed because of validation errors. - aborted: The AQuA job execution failed because one or more queries of this job failed. - cancelled: The AQuA job was cancelled.
  - `useLastCompletedJobQueries` boolean — If this flag is set to `true`, then all the previous queries are merged with existing queries. If the flag is set to `false`, then the previous queries are ignored, and only the new query is executed.
  - `version` number, float — The API version you want to use. The supported versions are as follows: - `1.1`. It supports both modes - `1.0`. Default. It supports stateless modes only. See <a href="https://knowledgecenter.zuora.com/Zuora_Central_Platform/API/AB_Aggregate_Query_API/BA_Stateless_and_Stateful_Modes" target="_blank">Stateless and stateful modes</a> for more information.

---

[API](https://skmtc.dev/zuora/apis/api-reference.md) · [All operations](https://skmtc.dev/zuora/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zuora/api-reference/revisions/702f3caf3985/schema)