# Invoice Runs

`GET /accounting/invoice-runs`

Group: Accounting › Invoice Runs · Operation ID: `invoiceRuns`

Returns a list of invoice runs. 'status' and 'scope' differ in type from GET accounting/invoice-runs/:id, which the endpoint description explains.

Lists invoice runs: what each was scoped to, when it ran and how it came out. Use it to audit billing activity or to find a run whose id you lost. Read a single run with GET accounting/invoice-runs/:id, which has the invoices and errors this list cannot.

Two fields differ from what GET accounting/invoice-runs/:id publishes. 'status' here is the stored value, not the corrected one, so a run whose worker was killed or lost reads 'running' without end, where the single-run endpoint reports 'error' instead. Treat any row that has been 'running' far longer than a run should take as unsettled, and read it through the single-run endpoint. 'scope' here is the raw stored text, the billed line types joined by semicolons into one string such as 'all', where the single-run endpoint publishes an array.

There is no 'customerId'. To find a customer's billing history, list invoices by customer instead.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=invoiceRuns)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Query surface

- `id` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `invoiceRunNumber` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `trigger` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `entityId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `salesOrderId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `startedAt` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `finishedAt` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `lastModifiedDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- Orderable: invoiceRunNumber, startedAt, finishedAt, lastModifiedDate
- Selectable: id, invoiceRunNumber, status, invoicesCreated, trigger, scope, entityId, salesOrderId, startedAt, finishedAt, lastModifiedDate

## Response

`200` Success

Under `data`, an array of invoiceRunsRow:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The unique identifier for the invoice run. |
| `invoiceRunNumber` | string or null | no | The invoice run number, for example 'ISR-1042'. |
| `status` | string or null | no | The execution status of the run, as stored rather than corrected, so a run whose worker was killed or lost reads 'running' without end. GET accounting/invoice-runs/:id reports 'error' for such a run instead. Possible values: 'created', 'running', 'completed', 'error', 'completeAndError'. |
| `invoicesCreated` | number or null | no | The number of invoices the run created. |
| `trigger` | string or null | no | What started the run. Possible values: 'immediately', 'daily', 'monthly'. |
| `scope` | string or null | no | The line types billed, as the raw stored text: the billed line types joined by semicolons into one string, such as 'all'. GET accounting/invoice-runs/:id publishes this as an array instead. |
| `entityId` | string or null | no | The legal entity billed. See id on GET base/entities. |
| `salesOrderId` | string or null | no | The sales order billed. Absent on a customer- or entity-scoped run. See id on GET accounting/sales-orders/:id. |
| `startedAt` | string (date-time) or null | no | The date and time the run was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `finishedAt` | string (date-time) or null | no | The date and time the run finished, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Absent while the run is still working, and on a run whose worker stopped without recording one. |
| `lastModifiedDate` | string (date-time) or null | no | The date and time the invoice run record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error