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

# voicegw export-costs

> Export per-request cost line items for a date window in CSV or JSON.

# voicegw export-costs

Export per-request cost line items for a date window in CSV or JSON.

## Purpose

The `export-costs` command writes one row per recorded request, suitable for spreadsheet review or as the input to a downstream reconciliation step. Pair with [`voicegw reconcile`](/cli/reconcile) to compare the exported numbers against a provider's invoice. The full reconciliation workflow lives at [Cost Reconciliation](/guide/cost-reconciliation).

## Syntax

```bash theme={null}
voicegw export-costs --start <YYYY-MM-DD> --end <YYYY-MM-DD> [OPTIONS]
```

## Options

| Flag        | Short | Type     | Default  | Description                                                                                               |
| ----------- | ----- | -------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `--start`   |       | `string` | required | Start date in `YYYY-MM-DD` (UTC, inclusive).                                                              |
| `--end`     |       | `string` | required | End date in `YYYY-MM-DD` (UTC, inclusive day; advanced one day internally for the exclusive upper bound). |
| `--project` | `-p`  | `string` | `null`   | Optional project filter.                                                                                  |
| `--format`  | `-f`  | `string` | `csv`    | Output format: `csv` or `json`.                                                                           |
| `--output`  | `-o`  | `string` | `-`      | Output path; `-` writes to stdout.                                                                        |
| `--config`  | `-c`  | `string` | `null`   | Path to `voicegw.yaml`. Auto-discovered if omitted.                                                       |

## Prerequisites

Cost tracking must be enabled in `voicegw.yaml`. If storage is not configured, the command prints a warning and exits with code 1.

## Output columns

Both formats use the same 10-column schema (locked by design §2.1).

| Column                | Type   | Notes                                                                                                                                                                                                 |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`           | string | ISO-8601 UTC (e.g., `2026-04-15T09:30:00+00:00`).                                                                                                                                                     |
| `project`             | string | Project ID; `default` if no project routing.                                                                                                                                                          |
| `modality`            | string | `stt`, `llm`, or `tts`.                                                                                                                                                                               |
| `provider`            | string | e.g., `openai`, `deepgram`, `cartesia`.                                                                                                                                                               |
| `model`               | string | Full `provider/model` string.                                                                                                                                                                         |
| `input_units`         | float  | Modality-dependent: tokens (LLM input), minutes (STT), characters (TTS).                                                                                                                              |
| `output_units`        | float  | Tokens (LLM output); 0 for STT and TTS.                                                                                                                                                               |
| `calculated_cost_usd` | string | Decimal-stable USD, fixed-point (no scientific notation), priced through `voice-prices`.                                                                                                              |
| `pricing_source`      | string | What priced this record: `voice-prices@<version>` for cloud models (e.g., `voice-prices@0.0.8`), `voicegateway-local` for self-hosted models (`local/*` and `ollama/*`), or empty for unknown models. |
| `status`              | string | `ok` or an error tag from the wrapper.                                                                                                                                                                |

Rows are ordered by timestamp ascending.

### JSON format (JSONL)

`--format json` emits **JSONL**: one JSON object per line, no
outer array, no indent. Streamable; downstream consumers iterate
`for line in f: row = json.loads(line)`. The schema matches the
CSV column set 1:1.

## Examples

### Export May 2026 to stdout as CSV

```bash theme={null}
voicegw export-costs --start 2026-05-01 --end 2026-05-31
```

### Export to a file

```bash theme={null}
voicegw export-costs --start 2026-05-01 --end 2026-05-31 --output may-2026.csv
```

A green confirmation line prints to stdout: `Wrote N record(s) to may-2026.csv`.

### Export as JSON for one project

```bash theme={null}
voicegw export-costs \
  --start 2026-05-01 --end 2026-05-31 \
  --project production \
  --format json \
  --output may-2026-production.json
```

## Exit codes

| Code | Meaning                                      |
| ---- | -------------------------------------------- |
| `0`  | Success.                                     |
| `1`  | Cost tracking is not enabled.                |
| `2`  | Bad input: malformed date or unknown format. |

## Related commands

* [`voicegw reconcile`](/cli/reconcile) -- diff the exported numbers against a provider's usage file.
* [`voicegw costs`](/cli/costs) -- aggregated summary instead of per-request rows.
* [`voicegw logs`](/cli/logs) -- recent rows for terminal display.

## See also

* [Cost Reconciliation](/guide/cost-reconciliation) -- the full reconciliation workflow.
* [Reconcile File Formats](/reference/reconcile-formats) -- per-provider schemas the reconcile step expects.