Skip to main content

AQuA API Introduction

Zuora

AQuA API Introduction

  1. Last updated
  2. Save as PDF

The Aggregate Query API (AQuA) is a REST API that executes multiple Export ZOQL or ZOQL queries. The queries are performed in a sequential order and in a single read-only database transaction.

Why Use AQuA API?

Using the AQuA API, you can do the following:

  • Continuously query data

You can export data incrementally, instead of exporting all of the data, all the time.

  • Export deleted data
  • Export files in segments

When you have large amounts of data, you can export your data in segments, instead of using bulky exports which can timeout.

In addition, AQuA API supports the following:

Authentication

Zuora recommends that you use OAuth v2.0 to authenticate to the REST API. Authenticating via OAuth requires the following steps:

  1. Create an OAuth client in the Zuora UI

  2. Generate a bearer token

  3. Authenticate subsequent API requests by providing a valid bearer token in an HTTP header:

    Authorization: Bearer {token}

If you have Zuora Multi-entity enabled and your bearer token is valid for more than one entity, use the Zuora-Entity-Ids header to specify which entity to perform each API request in. If your bearer token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set the Zuora-Entity-Ids header in your API calls.

See Authentication for more information about how to authenticate to the REST API.

Steps overview

  1. Submit an aggregate query job

  2. Retrieve the job results 

  3. Retrieve the result file

  4. View AQuA requests and results in the AQuA Job Finder (optional)

Limits

AQuA enforces the following limits:

  • The maximum processing time per query is 3 hours. If a query in an AQuA job is executed for longer than 3 hours, this job will be killed automatically. See the best practices for bulk data extraction with AQuA.
  • The maximum number of queries in an AQuA job is 50.
  • AQuA enforces limits on both the stateful concurrent AQuA jobs and the stateless concurrent AQuA jobs per tenant:
    • The maximum number of stateful concurrent AQuA jobs per tenant is 50.
    • The maximum number of stateless concurrent AQuA jobs per tenant is 50.
    AQuA jobs in the following status are counted towards your concurrent AQuA job limits:
    • Submitted
    • Executing
    Zuora system will reject the subsequent stateful or stateless job requests once the corresponding concurrent job limit is reached.
  • The ChargeMetrics and ChargeMetricsDiscountAllocationDetail objects are not available through AQuA. You can access them through Data Query or Charge Metrics API.