Exports in AI Cost Management

Exports in AI Cost Management write your stored usage events to downloadable files. Use them to analyze spend in a spreadsheet, load it into a data warehouse, or reconcile it with a model provider’s FOCUS data.

Create a one-time export to answer a question about a specific time range. Create a schedule to keep a recurring copy, for example a daily file for your finance team’s reporting.

Configuration options control what data an export holds, what format its files use, and how FOCUS rows are structured.

Datasets

The dataset controls what each row in an export holds and how the files divide the time range.

File formats

Exports are available in the following formats:

A period with no matching events still produces a file, with a header row only (CSV) or zero records (Parquet).

FOCUS options

FOCUS exports have additional options that control how rows are formed and what the cost columns hold.

FOCUS version

The FOCUS version controls what the standard cost columns (BilledCost, EffectiveCost, ListCost, ContractedCost) hold. Both versions carry the AI Gateway-reported cost estimate in x_ReportedCost.

Warning: If you load a FOCUS 1.3 file alongside a model provider’s own FOCUS data, the standard cost columns count the same spend twice. Use FOCUS 1.4 when combining exports with provider data.

Charge period

The charge period sets the length of each FOCUS row’s aggregation window, in the export’s time zone.

• day produces one row per calendar day
• hour produces one row per hour

An hour charge period also reduces the risk of a query_limit_exceeded failure on large datasets.

Tag keys

Tag keys name the tag dimensions that split FOCUS rows. A row’s Tags column holds each configured key and its value for the events the row aggregates. Each key must be between 1 and 128 characters, and a FOCUS export supports at most 64 tag keys.

The export lifecycle covers how an export progresses after creation, how to download its files, and how scheduled exports behave.

Status

An export runs asynchronously, and the status field tracks its progress.

Downloading files

You can download files from a successful export through short-lived URLs that the API returns. Each URL is valid for five minutes and works with a plain GET request without an Authorization header.

Warning: A download URL is a bearer credential. Anyone who holds it can download the file until it expires.

Each file in the export’s files list has a size_bytes and a sha256 field. The manifest.json file describes the export and lists each data file with its size and SHA-256 digest.

The files list doesn’t include the manifest. To download it, request a download URL with manifest.json as the filename. You can verify a download by comparing its size and SHA-256 checksum against those values.

Scheduled exports

A scheduled export runs automatically at the end of each period. Usage events don’t always arrive in real time. The export starts six hours after the period ends, so that events that arrive late can be stored first. For example, a request that happens at 11:58 PM might not be processed and stored until 1 AM.

Each schedule exports each period once and never refreshes it, even when events arrive after the export ran. A failed scheduled export stays failed and the schedule doesn’t retry it. To capture late events or fill a failed period, create a one-time export of the same range.

When a schedule resumes from paused, the periods that ended while it was paused are skipped. After an outage, a schedule catches up on at most the 31 most recent periods that ended while it was active.

To change a schedule, send a PUT request to the /v1/ai-cost-management/export-schedules/{scheduleId} endpoint with the full schedule, because an omitted filters clears the filters. Set status to paused to pause the schedule and to active to resume it. The change applies to periods that end after it, and existing exports don’t change.

You can create a one-time export or a recurring schedule from the Konnect UI or the API.

Set up a one-time export

curl -X POST "https://us.api.konghq.com/v1/ai-cost-management/exports" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "dataset": "usage_events",
       "format": "csv",
       "compression": "none",
       "from": "2026-10-01T00:00:00Z",
       "to": "2026-11-01T00:00:00Z",
       "time_zone": "UTC"
     }'

curl -X GET "https://us.api.konghq.com/v1/ai-cost-management/exports/$EXPORT_ID" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json"

curl -X POST "https://us.api.konghq.com/v1/ai-cost-management/exports/$EXPORT_ID/downloads" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "file": "'$FILE_NAME'"
     }'

Set up a scheduled export

curl -X POST "https://us.api.konghq.com/v1/ai-cost-management/export-schedules" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"\
     -H "Content-Type: application/json"\
     -H "Accept: application/json, application/problem+json" \
     --json '{
       "name": "daily-usage-events",
       "cadence": "daily",
       "time_zone": "UTC",
       "dataset": "usage_events",
       "format": "csv",
       "compression": "none"
     }'

Exports and export schedules are subject to the following limits.

Exports that a schedule creates don’t count toward the pending one-time export limit.

The following limitations also apply:

• An export runs once and is never refreshed. A later export of the same range can hold events an earlier one doesn’t have, because events can arrive after the range ends.
• Export files stay in the region where they were created.
• Labels on a one-time export can’t change after creation.
• A schedule’s cadence and time_zone can’t change after creation. Delete the schedule and create a new one to change either field.