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

# Air-gapped usage for billing

> Export usage data from air-gapped environments for billing purposes

## Overview

Usage data from Reducto deployments in air-gapped environments can be exported as a compressed CSV file and sent to Reducto for billing purposes.

When you invoke the `/billing-usage` API, usage data is exported from the database to a file and uploaded to the `BUCKET/usage_for_billing` prefix in object storage. A presigned URL is returned, which you can use to download the file and send it to Reducto.

**Note**: To avoid data loss, ensure that the exported file is downloaded and shared before any lifecycle rules expire and delete the object.

## Enable usage persistence

To export usage data, it must first be persisted in the database. This can be enabled by setting the following environment variable:

```bash theme={null}
STORE_USAGE_FOR_BILLING="yes"
```

## API reference

### POST `/billing-usage`

Exports usage data to object storage and returns a presigned URL for download.

#### Request parameters

| Parameter | Type    | Default   | Description                                            |
| --------- | ------- | --------- | ------------------------------------------------------ |
| `count`   | integer | 1,000,000 | The number of records to fetch and export (minimum: 1) |
| `delete`  | boolean | false     | Whether to delete the records after exporting          |

#### Request example

```bash theme={null}
curl -X POST "https://<your-endpoint>/billing-usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 100000,
    "delete": false
  }'
```

#### Response format

```json theme={null}
{
  "presigned_url": "<presigned-url>"
}
```

If usage persistence is not enabled or no data is available, the response will be:

```json theme={null}
{
  "presigned_url": null
}
```

## Exported data format

The exported CSV file contains the following columns:

* `idempotency_key`: Unique identifier for each usage record
* `type`: Type of usage (e.g., "parse")
* `num_pages`: Number of pages processed
* `attributes`: Additional metadata as JSON
* `timestamp`: When the usage occurred (ISO format)

## Usage workflow

1. **Enable persistence**: Set `STORE_USAGE_FOR_BILLING="yes"` in your environment
2. **Process documents**: Use Reducto normally; usage data will be automatically stored
3. **Export all data**: Call the `/billing-usage` API repeatedly with `"delete": true` until the presigned URL is null
4. **Download files**: Use each returned presigned URL to download the compressed CSV files
5. **Send to Reducto**: Share all downloaded files with Reducto for billing

### Complete data export process

To ensure all usage data is exported, you must call the API repeatedly with `delete: true` until no more data remains:

```bash theme={null}
set -eu

REDUCTO_ENDPOINT="https://<your-endpoint>"
REDUCTO_API_KEY="your-api-key"

# Call this repeatedly until presigned_url is null
while true; do
  echo "Exporting ..."
  response=$(curl -s -X POST "${REDUCTO_ENDPOINT}/billing-usage" \
    -H "Authorization: Bearer ${REDUCTO_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"count": 1000000, "delete": true}')
  
  presigned_url=$(echo "$response" | jq -r '.presigned_url')
  
  if [ "$presigned_url" = "null" ]; then
    echo "All data exported successfully"
    break
  fi
  
  echo "Downloading: $presigned_url"
  # Download the file using the presigned URL
  curl -OJ "$presigned_url"
done
```

**Important**: Always use `"delete": true` when performing complete exports to avoid re-exporting the same data and to free up database storage.

## Important notes

* Records are exported in chronological order (oldest first)
* The presigned URL expires after 6 days or until lifecycle rule deletes the object
* If `delete: true` is used, only successfully exported records are deleted from database
* To regenerate presigned URL of already exported data visit `BUCKET/usage_for_billing` prefix on cloud console for Bucket