> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unprice.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Settle run usage

> Account for actual usage after reserved work completes.

Use `runs.settle` when the provider has completed the work and you know the actual usage. Start the
run before work begins so customer funds are reserved. Settlement accounts for that usage and
leaves the run open. After all known usage is settled, call `runs.end` to close the run and
release unused reservation funds.

Use `runs.consume` to authorize a known usage amount before a billable step. Do not consume and
settle the same usage twice.

```ts theme={null}
const { result, error } = await unprice.runs.settle({
  runId: "brun_123",
  featureSlug: "ai-output-tokens",
  eventSlug: "completions",
  idempotencyKey: "run:req_123:settle",
  properties: { outputTokens: 620 }
});

if (error) throw new Error(`${error.code}: ${error.message}`);

if (!result.accepted) {
  throw new Error(`Settlement needs review: ${result.reason}`);
}

// End only after all billable usage has been settled successfully.
const { error: endError } = await unprice.runs.end({
  runId: "brun_123",
  status: "completed"
});

if (endError) throw new Error(`${endError.code}: ${endError.message}`);
```

## Request

| Field            | Meaning                                              |
| ---------------- | ---------------------------------------------------- |
| `runId`          | Required run ID returned by `runs.start`             |
| `featureSlug`    | Required feature whose meter prices the actual usage |
| `idempotencyKey` | Required stable key for this settlement              |
| `eventSlug`      | Event configured for the feature                     |
| `properties`     | Actual measured values required by the meter         |
| `timestamp`      | Event time in epoch milliseconds                     |
| `id`             | Optional event ID from your application              |

## Response and recovery

Check `accepted`, `reason`, and the returned `run` summary. When present, `fundingStatus`,
`fundedAmountMinor`, and `unfundedAmountMinor` describe how much usage the reserved funds covered.
Check these fields before treating the usage as fully funded.

Persist the actual usage and settlement key before sending the request. If the API call fails,
retry the same settlement with the same key. Do not call `runs.end` in a `finally` block to release
funds when provider usage exists but settlement is unconfirmed.

Use [End budgeted run](/libraries/ts/sdk/runs/end) to release unused funds after known usage has
been accounted for, or when no billable work occurred.