---
title: "List bill runs"
method: GET
path: "/object-query/billing-runs"
tags: ["Object Queries"]
---

# List bill runs

`GET /object-query/billing-runs`

Lists bill runs. You can use the query parameters to filter, expand, and sort the returned results.

## Query parameters

- `pageSize` integer
- `cursor` string
- `sort[]` string[]
- `expand[]` string[]
- `filter[]` string[]
- `fields[]` string[]
- `includeNullFields` boolean

## Headers

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

## Response `200`

OK

- object
  - `nextPage` string, nullable — A string that can be used as the `cursor` value to retrieve the next page of the response if it exists; otherwise absent.
  - `data` ExpandedBillingRun[]
    - `id` string — The unique identifier of the bill run.
    - `createdById` string — The unique identifier of the user who created the bill run.
    - `createdDate` string, date-time — The date and time when the bill run was created.
    - `updatedById` string — The unique identifier of the user who last updated the bill run.
    - `updatedDate` string, date-time — The date and time when the bill run was last updated.
    - `billingRunNumber` string — The number of the bill run.
    - `billingRunType` 'Regular' | 'CatchUp' — The type of the bill run. - You can use this field only if the Catch-Up Bill Run feature is enabled. - You must specify this field to create a catch up bill run.
    - `endDate` string, date-time — The end date and time when the bill run completes.
    - `errorMessage` string — The error message generated by a failed billing run.
    - `executedDate` string, date-time — The date and time when the bill run was executed.
    - `invoiceDate` string, date — The date that appears on the invoice being created, in the `yyyy-mm-dd` format. The value cannot fall in a closed accounting period.
    - `name` string — The name of the bill run.
    - `numberOfAccounts` integer — The number of accounts included in this bill run processing.
    - `numberOfInvoices` integer — The number of invoices generated from this bill run.
    - `numberOfCreditMemos` integer — The number of credit memos generated from this bill run.
    - `postedDate` string, date-time — The date when the bill run was posted.
    - `startDate` string, date-time — The start date and time of the bill run.
    - `status` 'Pending' | 'Processing' | 'Completed' | 'Error' | 'Canceled' | 'Posted' | 'PostInProgress' | 'CancelInProgress' | 'RemoveInProgress' | 'Paused' — The status of the bill run.
    - `targetDate` string, date — The target date for this bill run, only valid for ad-hoc bill runs.
    - `targetType` 'SingleAccount' | 'AllAccount' — The target type for this bill run.
    - `totalTime` integer — The total time in milliseconds for the bill run to complete.
    - `accountId` string — The unique identifier of the account included in the bill run.
    - `batches` string[] — The batch of accounts for this bill run, this field can not exist with `billRunFilters` together. **Values:** `AllBatches` or an array of `Batch`*n* where *n* is a number between 1 and 50, for example, `Batch7`.
    - `billCycleDay` 'AllBillCycleDays' | 'AsRunDay' — The day of the bill cycle. This field is only valid when `batches` is specified. **Values:** - `AllBillCycleDays` or one of numbers 1 - 31 for an ad-hoc bill run - `AllBillCycleDays`, one of numbers 1 - 31, or `AsRunDay` for a scheduled bill run
    - `noEmailForZeroAmountInvoice` boolean — Whether to suppress emails for invoices with zero total amount generated in this bill run after the bill run is complete.
    - `autoEmail` boolean — Whether to automatically send emails after Auto-Post is complete.
    - `autoPost` boolean — Whether to automatically post the bill run after the bill run is created.
    - `autoRenewal` boolean — Whether to automatically renew auto-renew subscriptions that are up for renewal.
    - `invoicesEmailed` boolean — Whether the invoices have been emailed after the bill run is complete.
    - `lastEmailSentTime` string, date-time — The date and time when the last email was sent.
    - `targetDateOffSet` integer — The offset compared to bill run execution date, only valid for scheduled bill runs.
    - `invoiceDateOffSet` integer — The offset compared to bill run execution date, only valid for scheduled bill runs.
    - `chargeTypeToExclude` 'OneTime' | 'Recurring' | 'Usage' — The types of the charges to be excluded from the generation of billing documents.
    - `scheduledExecutionTime` string, date-time — The scheduled execution time for a bill run.
    - `repeatType` 'None' | 'Daily' | 'Weekly' | 'Monthly' — The repeat type of the bill run.
    - `repeatFrom` string, date — The start date of the scheduled bill run.
    - `repeatTo` string, date — The end date of of the scheduled bill run.
    - `runTime` integer — The scheduled run time (hour) of day.
    - `timeZone` string — Timezone of the scheduled bill run.
    - `monthlyOnDay` string — The repeat day in a month.
    - `weeklyOnDay` 'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri' | 'Sat' | 'Sun' — The repeat day in a week.
    - `includeSubscriptions` boolean — Indicates whether to bill subscriptions in the bill run.
    - `includeOrderLineItems` boolean — Indicates whether to bill order line items in the bill run.

## Other responses

- `500` — Internal server error
- `4XX` — Invalid input

---

[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/d11e237f3e54/schema)