Download OTLP spans as a file

post

https://api.eu-west-1.aws.dash0.com/api/spans/download

Returns the spans matching the given query as a downloadable file in the requested
format (txt, ndjson, yaml or csv).

A single export is capped at 5000 spans. A limit above that cap is rejected
rather than silently clamped: the response is a client error naming the cap. When the
query matches more than 5000 spans, the export carries the first 5000 in result-set
order. Use the Dash0 CLI (dash0 spans query) to export larger volumes.

The spans are the same ones POST /api/spans returns for the same query, except that
adaptive sampling is always disabled for exports: an exported file is never a sample,
whatever the query and whatever the data volume. This request accordingly takes no
sampling, and one sent anyway is ignored.

The response is streamed as pages are retrieved and therefore carries no
Content-Length. Because the response headers are committed before the first span
is written, a failure partway through cannot be reported as a status code — it
terminates the transfer instead. Clients MUST confirm the body was received completely
before treating the download as a successful export.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Request for the SpansDownload API. Accepts the same query as GetSpans
(filter, timeRange, dataset, ordering) and returns the matching spans
serialized as a downloadable file rather than as a JSON page.

The response is streamed, so the export is not paginated: a single request returns up
to limit spans, capped at 5000. Adaptive sampling is always disabled for exports,
so an exported file is never a sample. Unlike GetSpans this request therefore takes
no sampling, and one sent anyway is ignored: the sampling path can substitute a
duration-percentile filter and quietly change which spans the file contains, so
exports never take it.

filter

array of objects

filter

timeRange

object

required

A range of time between two time references.

dataset

string

^[a-zA-Z0-9_-]{3,26}$

Optional dataset to query across. Defaults to whatever is configured to be the default dataset for the organization.

ordering

array of objects

The ordering criteria for the exported spans. Spans are written to the file in
this order.
Supported ordering key: otel.span.start_time (span start timestamp, defaults to
descending), optionally followed by otel.trace.id then otel.span.id ascending,
which is the tiebreak span retrieval appends to keep its cursor stable.

ordering

format

string

enum

required

The serialization format of the exported file.

txt: One rendered span line per record, carrying a fixed field set of start
timestamp, service, span name, duration, kind, status code, trace ID and span ID.
Ignores columns.
ndjson: One OTLP JSON payload per line, each carrying a single span inside the
same resourceSpans envelope GetSpans returns, so each line is independently
parseable by any OTLP JSON consumer.
yaml: The same per-span OTLP payloads as ndjson, as a multi-document YAML
stream with documents separated by ---.
csv: A header row plus one row per span, flattened to the requested columns.

Allowed:

limit

int64

1 to 5000

Defaults to 5000

The maximum number of spans to export. Defaults to, and is capped at, 5000.
A larger value is rejected rather than silently clamped. Use the Dash0 CLI
(dash0 spans query) to export volumes beyond this cap.

columns

array of strings

Attribute keys to emit as columns, in order, for the csv format — resource,
scope, or span attributes (e.g. service.name, otel.span.duration). Ignored by
the other formats, which have a fixed field set.

columns

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/octet-stream

application/json

200The exported spans. The body's actual content type matches the requested format (text/plain for txt, application/x-ndjson for ndjson, application/yaml for yaml, text/csv for csv).

400The request is invalid, for example a limit above the 5000-record cap, an unsupported ordering, or a time range exceeding the maximum permitted query range. No partial file is produced.

403Forbidden - the requested dataset is not accessible

defaultIn case any error happens.