Skip to main content

export-datahub-dataset-records 

dci export-datahub-dataset-records <name> [flags]

Returns one page of the live records of a DataHub dataset, as CSV (default) or as newline-delimited JSON in the same shape as the /datahub/v1/events payload.

A time window is required: startTime is inclusive, endTime is exclusive, and the window must not exceed 366 days. Rows are ordered by their event time and event id, and pages never overlap: read the X-Next-Page-Token response header and pass it back as pageToken until the header is absent. X-Row-Count carries the number of rows in the page. Only live rows are returned; rows deleted through the console or the delete endpoints are excluded.

Every row starts with five provenance columns (event_id, batch, source, export_time, updated_by) followed by the dataset's business columns in the CSV ingest vocabulary (usage_date, fixed.&lt;key&gt;, label.&lt;key&gt;, project_label.&lt;key&gt;, system_label.&lt;key&gt;, metric.&lt;type&gt;). The business columns are computed from the rows of each page, so consecutive pages can have different label and metric columns; union the headers when concatenating pages. Datasets created with the FOCUS schema template use the FOCUS column names instead and can only be exported as CSV.

To re-import an export into another dataset, drop the batch, source, export_time and updated_by columns, and either drop event_id or rename it to id.

  • name — Dataset name as shown by dci list-datahub-datasets — the dataset's identifier and its ingest provider value, never a display name.
CLI behavior

The response body of this command is a file, not a table, so the CLI prints it exactly as the API sent it — CSV by default, newline-delimited JSON with --format jsonl. --output is ignored for this command; use --output-file to save the bytes.

  • --all fetches everything. The continuation token for this endpoint arrives in the X-Next-Page-Token response header rather than in the body, and the API exports at most 366 days per request. --all follows the tokens and walks the successive time windows, then merges the pages into one export: pass the full range you want and the CLI covers it. It reports on stderr how many pages and windows it merged.
  • --all on its own exports the whole dataset. The API requires both time bounds, so with neither given --all finds the range: it looks backwards from now one 366-day window at a time, asking each for a single row, and starts the export at the oldest window that has any (stopping after two consecutive empty windows). The range it settled on is printed on stderr. Two years of data costs four extra one-row requests. Pass --start-time/--end-time when you want an exact window — or when a dataset has more than two years with no rows at all before older ones.
  • Merged CSV pages share one header. The API computes the business columns from the rows of each page, so consecutive pages can carry different label.* and metric.* columns; --all re-emits every row against the union of the headers, so a value never lands under the wrong column. A single-page export is passed through byte for byte.
  • Without --all, a truncated export says so. When more rows remain, the CLI prints the row count and the --page-token value to stderr — nothing in a CSV or JSONL stream itself would reveal that the file is partial.
  • A window wider than 366 days is rejected before the request, with a pointer to --all, instead of returning the API's bare 400. So is a missing bound without --all: the API needs both, and --all is how you say "all of it".
  • --output-file takes a path, or a directory (--output-file .) to use the filename from the API's Content-Disposition header. A write that fails partway removes the partial file rather than leaving it behind.
  • --search does not apply and is rejected: it filters the items of a list response, and this command returns a file. Filter the export itself with grep, jq, or a spreadsheet.
  • --for-reimport rewrites the CSV into the ingest vocabulary: it drops the export-only batch, source, export_time and updated_by columns and renames event_id to id, which is exactly what dci ingest-datahub-events-csv expects. It applies to CSV only.
  • Only live rows are exported; rows deleted in the console or through the delete endpoints are excluded. Datasets created from the FOCUS schema template export FOCUS column names and CSV only.

Examples​

# The entire dataset to a file — the CLI finds the data's time range itself.
dci export-datahub-dataset-records <dataset-name> --all --output-file records.csv
# One month of records as CSV, printed to the terminal.
dci export-datahub-dataset-records <dataset-name> --start-time 2026-08-01T00:00:00Z --end-time 2026-09-01T00:00:00Z
# The whole dataset to a file, however many pages and 366-day windows that takes.
dci export-datahub-dataset-records <dataset-name> --start-time 2025-01-01T00:00:00Z --end-time 2026-09-05T00:00:00Z --all --output-file records.csv
# Save under the filename the API suggests, into the current directory.
dci export-datahub-dataset-records <dataset-name> --start-time 2026-08-01T00:00:00Z --end-time 2026-09-01T00:00:00Z --output-file .
# The event-shaped JSON export (one JSON object per line), for a script or another tool.
dci export-datahub-dataset-records <dataset-name> --start-time 2026-08-01T00:00:00Z --end-time 2026-09-01T00:00:00Z --format jsonl --all --output-file records.jsonl
# Export ready to load into another dataset — provenance columns dropped, event_id renamed to id — then upload it with ingest-datahub-events-csv.
dci export-datahub-dataset-records <dataset-name> --start-time 2026-08-01T00:00:00Z --end-time 2026-09-01T00:00:00Z --all --for-reimport --output-file records.csv
# One page at a time, following the page token by hand.
dci export-datahub-dataset-records <dataset-name> --start-time 2026-08-01T00:00:00Z --end-time 2026-09-01T00:00:00Z --max-results 5000

Flags​

FlagTypeDefaultExampleDescription
--formatstring"csv"Output format. One of: "csv", "jsonl".
--start-timestring (date-time)2026-01-01T00:00:00ZInclusive lower bound on the event time, RFC3339.
--end-timestring (date-time)2026-02-01T00:00:00ZExclusive upper bound on the event time, RFC3339. At most 366 days after the start time.
--max-resultsinteger (int64)10000Maximum number of rows in the page.
--page-tokenstringPage token, returned by a previous call, to request the next page of results

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

OK - One page of records. The body is streamed.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Returns: string (binary)

Raw JSON schema
{
  "type": "string",
  "format": "binary"
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
42950RATE_LIMITEDToo many requests. Retryable — the CLI reports the server-provided delay.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.