Export Usage

Open Spanner can export usage query results as CSV. Use exports when another system wants files for billing imports, finance reports, support audits, or product analytics.

Open Spanner supports direct CSV exports for small requests and queued export jobs for longer-running files. Direct exports return CSV from the API request and are limited to focused result sets. Queued export jobs are processed by the export worker and can be downloaded after completion.

Export A Window

Use the simple export form when meter, subject, time window, grouping, and basic metadata filters are enough.

curl "http://localhost:18081/v1/usages/export?subject=org_123&meter=api_requests&from=2026-06-01T00:00:00Z&to=2026-06-10T00:00:00Z&bucket_size=day" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
  -o usage.csv

Export By Metadata

Use filtered export when the CSV should match a richer usage query. This is the same query shape used by usage search, so nested filters, numeric comparisons, metadata filters, and grouping all stay together.

curl "http://localhost:18081/v1/usages/export" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meter": "api_requests",
    "from": "2026-06-01T00:00:00Z",
    "to": "2026-06-10T00:00:00Z",
    "bucket_size": "day",
    "group_by": ["endpoint", "status_code"],
    "filter": {
      "type": "group",
      "op": "and",
      "rules": [
        { "type": "condition", "field": "metadata.endpoint", "op": "contains", "value": "/api/" },
        { "type": "condition", "field": "quantity", "op": "gte", "value": 1 }
      ]
    }
  }' \
  -o usage.csv

Keep dimension names stable when another system depends on the CSV columns.

Export Raw Events

Bucketed exports are usually better for billing and reporting because they match the same aggregation model as usage search. Raw event exports are useful when another system needs the underlying events for audit or reconciliation.

curl "http://localhost:18081/v1/usageevents/export?meter=api_requests&from=2026-06-01T00:00:00Z&to=2026-06-02T00:00:00Z&limit=1000" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
  -o usage-events.csv

Raw event exports use the same direct export limit. For large audits, export narrow time ranges and combine the files outside Open Spanner.

Queued Export Jobs

Use queued exports when a report may take longer than a normal request or when a user wants to come back to a generated file later. The API creates the job, and the export worker claims queued jobs from storage, writes CSV files, and marks jobs completed.

The API and worker must share the same database and export storage path. Docker Compose starts both services with a shared export volume. If you run containers manually, start open-spanner and open-spanner-export-worker with the same /data volume.

curl "http://localhost:18081/v1/exports" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "usage_buckets",
    "format": "csv",
    "query": {
      "meter": "api_requests",
      "from": "2026-06-01T00:00:00Z",
      "to": "2026-06-10T00:00:00Z",
      "bucket_size": "day",
      "group_by": ["endpoint"],
      "limit": 1000
    }
  }'

Check the job until it is completed:

curl "http://localhost:18081/v1/exports/{job_id}" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY"

Completed jobs include a download_url. Download the file from that URL:

curl "http://localhost:18081/v1/exports/{job_id}/download" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
  -o usage-export.csv

Cancel a queued or running job:

curl -X POST "http://localhost:18081/v1/exports/{job_id}/cancel" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY"

Retry a failed or canceled job:

curl -X POST "http://localhost:18081/v1/exports/{job_id}/retry" \
  -H "Authorization: Bearer $OPEN_SPANNER_API_KEY"

Run the export worker beside the API process when queued exports are enabled. Docker Compose starts both services. For a task-based local run, use task run:export-worker or task run:export-worker:postgres with the same database and export storage path as the API.