---
title: "Start DCI history export"
method: POST
path: "/v1/data-export"
tags: ["Data Export"]
---

# Start DCI history export

`POST /v1/data-export`

## Request

- Base URL: `http://127.0.0.1:8000`
- URL: `http://127.0.0.1:8000/v1/data-export`
- Auth: HTTP bearer

Start a server-side export of DCI history for metrics selected either by system tag patterns under a root object or by an explicit DCI list. The export runs as a background task; poll GET /v1/data-export/{task-id} for progress and download the produced archive from GET /v1/data-export/{task-id}/file once the task is completed. The archive is a ZIP with metrics.csv (one row per metric, including the classifier tag and a stable metric identifier), data.csv (one row per sample, with provenance attributes) and manifest.json. With "anonymize" set, object names are replaced with class-based pseudonyms and metric identifiers with HMAC-derived pseudonyms that stay stable across exports from the same server; numeric object identifiers and the server identifier are omitted from the archive. "keepMapping" additionally produces a pseudonym-to-identity mapping file that is downloaded separately and is never part of the archive. Requires read access to the root object and to every exported DCI; related objects and spatial ancestors are included only when readable. The period end is clamped to the current time. Every export is recorded in the audit log.

## Request body

- DataExportRequest
  - `rootObjectId` integer: Root of the object subtree searched for tagged DCIs; required unless dciList is given
  - `tagPatterns` string[]: Glob patterns (* and ? wildcards) matched against DCI system tag, e.g. "eed.*"
  - `dciList` object[]: Explicit metric selection; when not empty, rootObjectId and tagPatterns are ignored
    - `ownerId` integer, required: Object ID of the DCI owner
    - `dciId` integer, required: DCI ID
  - `timeFrom` union, required: Start of export period (ISO 8601 string or UNIX time in seconds)
    - string, date-time
    - integer
  - `timeTo` union, required: End of export period, inclusive (ISO 8601 string or UNIX time in seconds)
    - string, date-time
    - integer
  - `tier` 'raw' | 'hourly' | 'daily': History tier to export. Aggregated tiers produce one row per bucket with average in "value" and additional min, max and count columns; metrics for which the requested tier is not available fall back to raw samples.
  - `format` 'csv': Output format
  - `anonymize` boolean: Replace object names with class-based pseudonyms and metric identifiers with stable pseudonyms
  - `keepMapping` boolean: Produce pseudonym mapping file (anonymized exports only), downloadable with type=mapping

## Response `201`

Export task started

- object
  - `taskId` integer: Background task ID

## Other responses

- `400`: Invalid request (bad time period, unknown tier, unsupported format, no selection)
- `401`: Unauthorized
- `403`: No read access to root object
- `404`: Root object not found

## Changes

- **2026-10-19** `290af90fdb5a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/netxms/apis/netxms-api/changes/v1/data-export/post.md)

---

[API](https://skmtc.dev/netxms/apis/netxms-api.md) - [All operations](https://skmtc.dev/netxms/apis/netxms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/netxms/apis/netxms-api/revisions/740d85ba6674?raw)