# Returns one invoice run and its outcome.

`GET /accounting/invoice-runs/{id}`

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

Reads one invoice run: what it was scoped to, where it got to, the invoices it created and the lines that failed. This is the poll half of POST accounting/invoice-runs.

Branch on 'status'. 'created' and 'running' mean keep polling. 'completed' means every selected line was billed. 'error' means nothing was billed and 'errors' says why. 'completeAndError' means some invoices were created and some lines failed, so check 'status' rather than assuming success once 'invoicesCreated' is non-zero.

'status' is corrected against the worker running the job. The stored status settles only when the run records a finish time, which a killed, canceled or lost worker never does, so such a run would otherwise read 'running' without end. Where that has happened this endpoint reports 'error', so a polling loop always ends.

No total amount is published for the run. Each entry in 'invoices' has its own 'totalAmount' and 'currency' instead, because a run can create invoices in several currencies and one summed figure would add unlike units.

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

## 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`. |
| `id` | path | string | yes | The unique identifier for the invoice run to return. |

## Response

`200` Success

Under `data` (getInvoiceRunOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object | yes | The requested invoice run. |
| `data.id` | string | yes | The unique identifier for the invoice run. |
| `data.invoiceRunNumber` | string | no | The invoice run number, for example 'ISR-1042'. Absent while none has been assigned. |
| `data.status` | string | yes | The execution status of the run. Possible values: 'created', 'running', 'completed', 'error', 'completeAndError'. Keep polling on 'created' and 'running'. 'completeAndError' means some invoices were created and some lines failed. |
| `data.invoicesCreated` | number | yes | The number of invoices the run has created. |
| `data.startedAt` | string | no | The date and time the run was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `data.finishedAt` | string | 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. |
| `data.lastModifiedDate` | string | no | The date and time the invoice run record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `data.trigger` | string | no | What started the run. Possible values: 'immediately', 'daily', 'monthly'. 'immediately' is an ad-hoc run. 'daily' and 'monthly' are scheduled. |
| `data.scope` | array of string, one of `"all"`, `"oneTimeAndRecurring"`, `"usageInArrears"`, `"billableProducts"` | yes | The line types the run billed. |
| `data.entityId` | string | no | The legal entity billed. See id on GET base/entities. |
| `data.salesOrderId` | string | no | The sales order billed. Present on a sales-order-scoped run. See id on GET accounting/sales-orders/:id. |
| `data.customerId` | string | no | The customer billed. Absent on a run that created no invoice and recorded no error. See id on GET accounting/customers/:id. |
| `data.progress` | object | no | The run's own progress reporting while it works. It is advisory: absent before the run starts reporting, and never a substitute for 'status'. |
| `data.progress.title` | string | no | The phase the run is in, for example preparing data or creating invoices. |
| `data.progress.message` | string | no | Further detail on the current phase, when the run supplies any. |
| `data.progress.progress` | number | no | The number of items processed so far in the current phase. |
| `data.progress.total` | number | no | The number of items to process in the current phase. |
| `data.invoices` | array of object | yes | The invoices the run created. Each has its own currency, so there is no summed run total. |
| `data.invoices[].id` | string | yes | The unique identifier for the invoice. See id on GET accounting/invoices/:id. |
| `data.invoices[].invoiceNumber` | string | no | The invoice number, for example 'INV-20841'. |
| `data.invoices[].totalAmount` | string (decimal) | no | The total amount of the invoice including tax, in the currency named by 'currency'. |
| `data.invoices[].currency` | string | no | The currency of the invoice. Format ISO 4217, for example 'EUR'. |
| `data.errors` | array of object | yes | The lines the run could not bill, one entry each. A non-empty array with a non-zero 'invoicesCreated' is the 'completeAndError' outcome. |
| `data.errors[].type` | string | yes | Why the line could not be billed. Possible values: 'system', 'avalaraAddress', 'taxCode', 'none', 'taxCalculation', 'vatEntity', 'accountConfig', 'vatCustomer', 'invoiceSetupIncomplete', 'invoiceDelivery'. |
| `data.errors[].detail` | string | no | A description of why the line failed. |
| `data.errors[].customerId` | string | no | The customer the failing line belongs to. See id on GET accounting/customers/:id. |

## Errors

| Code | Status |
| --- | --- |
| `NOT_FOUND` | 400 |

## Statuses

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