# List invoice runs

Operation ID: `invoiceRuns`

Group: Accounting › Invoice Runs

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/invoiceRuns)

`GET /accounting/invoice-runs`

Read-only: Reads and returns; changes nothing.

Lists invoice runs. The collection doesn't include customerId, invoices, errors, or progress. To see a run's invoices and errors, use GET accounting/invoice-runs/:id.

If a run shows 'running' for much longer than a run usually takes, read the run with GET accounting/invoice-runs/:id to get its corrected 'status'. 'scope' here is one text value, where GET accounting/invoice-runs/:id returns an array.

To find a customer's invoices, use GET accounting/invoices filtered by customerId.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | string · 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
- `finishedAt` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- `lastModifiedDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between
- Orderable: invoiceRunNumber, startedAt, finishedAt, lastModifiedDate
- Selectable: id, invoiceRunNumber, status, invoicesCreated, trigger, scope, entityId, salesOrderId, startedAt, finishedAt, lastModifiedDate
- `page[size]` — Page size
- `page[cursor]` — Opaque continuation cursor

## Response

`200` Success

Under `data`, an array of invoiceRunsRow:

| Field | Type | Required | Filter | Sort | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | string | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | The unique identifier for the invoice run. Example: `"1c9d6b73-4a20-4e58-8f31-7b2e0c4a9d15"`. |
| `invoiceRunNumber` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | yes | The invoice run number, for example 'ISR-1042'. Example: `"ISR-1042"`. |
| `status` | string \| null | no | no | 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'. Example: `"completed"`. |
| `invoicesCreated` | number \| null | no | no | no | The number of invoices the run created. Example: `3`. |
| `trigger` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | What started the run. Possible values: 'immediately', 'daily', 'monthly'. Example: `"immediately"`. |
| `scope` | string \| null | no | no | 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. Example: `"all"`. |
| `entityId` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | The legal entity billed. See id on GET base/entities. Example: `"6f1b2a84-3d97-4c25-8e60-9a4f0b7d1c53"`. |
| `salesOrderId` | string \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`), Pattern (`like`) | no | The sales order billed. Absent on a customer- or entity-scoped run. See id on GET accounting/sales-orders/:id. Example: `"8f14e45f-ceea-467a-9f6b-2c1d0e5a7b39"`. |
| `startedAt` | date-time \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The date and time the run was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-09-30T08:14:22.000Z"`. |
| `finishedAt` | date-time \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | 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. Example: `"2026-09-30T08:14:41.000Z"`. |
| `lastModifiedDate` | date-time \| null | no | Exact (`eq`, `ne`), Range (`gt`, `gte`, `lt`, `lte`, `between`), Any of (`in`, `notIn`) | yes | The date and time the invoice run record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-09-30T08:14:41.000Z"`. |

```json
{
  "data": [
    {
      "id": "1c9d6b73-4a20-4e58-8f31-7b2e0c4a9d15",
      "invoiceRunNumber": "ISR-1042",
      "status": "completed",
      "invoicesCreated": 3,
      "trigger": "immediately",
      "scope": "all",
      "entityId": "6f1b2a84-3d97-4c25-8e60-9a4f0b7d1c53",
      "salesOrderId": "8f14e45f-ceea-467a-9f6b-2c1d0e5a7b39",
      "startedAt": "2026-09-30T08:14:22.000Z",
      "finishedAt": "2026-09-30T08:14:41.000Z",
      "lastModifiedDate": "2026-09-30T08:14:41.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "<nextCursor>"
  }
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error