Exports

Before you start

• Object storage configured (see Configuration)
• The member, admin or owner role in the project (viewers cannot export)

Start an export from the Traces page: it exports the traces that match the filters you have set, as CSV (one row per trace) or JSONL (one trace per line, with its spans). Follow it and download the file in Settings, Project, Exports. Exports need object storage, and the file is kept in your own bucket.

• A time range is required and can span at most 90 days. More than 100 000 matching traces fail the export as too large; narrow the range.
• Members, admins and owners can export. Viewers cannot.
• The export runs in the background. When it is done, the dashboard offers a download link that is valid for one hour; open the export again for a fresh one.
• Files are deleted seven days after they are made, and when the project is deleted.
• Spreadsheet cells that begin with =, +, - or @ are prefixed with an apostrophe, so opening the file cannot run a formula.
• The trace’s metadata is in the last CSV column, metadata, as a JSON object with its keys sorted, and in JSONL as a metadata object. A metadata filter on the Traces page applies to the export.

Requesting an export (POST /api/v1/projects/{project_id}/exports) accepts an Idempotency-Key header, so a retried request runs once and returns the same export. Use a fresh random key, such as a UUID, for each intended export. A key belongs to the caller that sent it (a user, or an API key), is remembered for 24 hours, and the same key with a different body is 422 IDEMPOTENCY_MISMATCH. A 409 NOT_CONFIGURED is remembered too, so after switching object storage on, retry with a new key. Other routes ignore the header.

Export the attribution table

On the Attribution page, Export opens Export attribution: the format is CSV, and What’s exported repeats the window, the group, the environment and whether the table is live or read from the daily rollup. Start export queues it like a trace export. The button is off for viewers, before a metadata key is picked, and for a key that is not promoted over a window longer than 24 hours.

Through the API, the request follows the same rules as the page: a window over 24 hours reads the daily rollups, so a metadata key must be promoted (422 KEY_NOT_PROMOTED otherwise), and the window can span at most 90 days. SPANLIGHT_TOKEN is a personal access token with the write scope; an API key cannot export.

curl -sS -X POST "$SPANLIGHT_HOST/api/v1/projects/$PROJECT/exports" \
  -H "Authorization: Bearer $SPANLIGHT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind": "attribution", "format": "csv", "group_by": "metadata", "key": "customer_id",
       "filters": {"from": "2026-09-16T00:00:00Z", "to": "2026-10-16T00:00:00Z", "environment": "production"}}'

group_by is metadata (with key), trace_name, user or release, and environment is optional. Only CSV is offered. The file has one row per value, costliest first, then the traces without the dimension, then, over more than 24 hours, the values folded past the daily cap:

Column	Holds
group_by, key	What the table is grouped by
value	The value; empty on the none and other rows
bucket	value, none or other
traces, llm_calls, errors, unpriced_calls, input_tokens, output_tokens	The group’s counts and tokens
cost_usd, retries, retry_cost_usd	The group’s cost and retries; an empty cell is unknown, never zero
folded_values	On the other row only: how many values it folds, at most (a value folded on two days counts twice)

A value such as =HYPERLINK(…) gets the apostrophe like any other cell. More than 100,000 rows fail the export with EXPORT_TOO_LARGE. The export is listed and downloaded like a trace export.

The audit log has its own CSV download in Settings, Organization, Audit log. The filters you set apply, and up to 50 000 events fit in one file.

Check it worked

On Traces, press Export, pick CSV or JSONL and press Start export. The dialog changes to Export queued. In Settings, Project, Exports the new row goes from Queued to Running to Done, and a Download button appears. The page checks again every three seconds while an export is queued or running.

Troubleshooting

• The Export button is off. A viewer cannot export (“Viewers can’t export traces. Ask an admin for access.”).
• The dialog says “Not available on this server” (“Exports need object storage. Ask your administrator to set the S3 settings.”). The server answered 409 NOT_CONFIGURED. An operator sets the S3 settings in Configuration; then retry with a new request, since the refusal is remembered for the same Idempotency-Key.
• “Exports cover at most 90 days. Narrow the time range on the Traces page, then export again.” The range is over 90 days. Start export stays off until you narrow it.
• The row reads “Failed” with EXPORT_TOO_LARGE (“More than 100,000 traces. Narrow the time range and export again.”). Narrow the range or add filters.
• The row reads “Failed” with EXPORT_TIMEOUT or EXPORT_FAILED. Building the file took too long, or failed. Export again with a narrower range.
• The row reads “Failed” with NOT_CONFIGURED (“Object storage was switched off before the file was written.”). Object storage was turned off while the export ran. Switch it on in Configuration and export again.
• The row reads “Expired”, or Download says “This export is no longer available. It may have expired.” Files are deleted after seven days. Start a new export.
• The row stays “Queued”. The worker builds exports; check that it is running (see the troubleshooting page).

Next steps

Data, limits and operationsRate limits, backups and monitoring Spanlight itself.

ConfigurationEvery environment variable the API and worker read.

Exports endpointsThe routes behind exports.