---
title: "Get data collection history"
method: GET
path: "/v1/objects/{object-id}/data-collection/{dci-id}/history"
tags: ["Data Collection"]
---

# Get data collection history

`GET /v1/objects/{object-id}/data-collection/{dci-id}/history`

Retrieve historical data for a specific DCI (Data Collection Item).

The server can serve data from one of three storage tiers: raw samples, hourly
aggregates, or daily aggregates. The `tier` query parameter selects which tier to
read from (default `auto`, which picks the densest tier whose point count fits
within the server-side `DataCollection.Aggregation.MaxAutoSelectPoints` threshold).
When the resolved tier is hourly or daily, each row carries pre-computed avg/min/max
and a `sampleCount` of raw samples that contributed to the bucket. The `function`
query parameter selects which value column(s) the server returns from the aggregate
tables (`minmax` returns avg, min, and max in a single response for band rendering).

## Path parameters

- `object-id` integer, required — Object ID
- `dci-id` integer, required — DCI (Data Collection Item) ID

## Query parameters

- `timeFrom` integer — Start time for data retrieval (Unix timestamp)
- `timeTo` integer — End time for data retrieval (Unix timestamp)
- `maxRows` integer — Maximum number of data points to return
- `maxDataPoints` integer — When the request resolves to the raw tier, perform on-the-fly bucketing into this many points and return avg/min/max per bucket. Ignored on hourly/daily tier reads (those already serve pre-computed buckets).
- `historicalDataType` integer — Type of historical data (0=processed, 1=raw, 2=raw and processed, 3=full table)
- `tier` 'auto' | 'raw' | 'hourly' | 'daily' — Storage tier to read from. `auto` picks the densest tier whose point count fits the server-side auto-select threshold. Explicit tiers are downgraded to raw when the requested aggregate is not available for the DCI (e.g. string DCIs, or non-TSDB targets where the per-object aggregate table has not been created yet). The actually-served tier is reported in `tierServed`.
- `function` 'avg' | 'min' | 'max' | 'minmax' — Aggregation function for hourly/daily tier reads. `minmax` returns `avg`, `min`, and `max` columns in a single response, suitable for band-graph rendering. Ignored when `tierServed` is `raw`.

## Response `200`

Data collection history retrieved successfully

- object
  - `description` string — DCI description
  - `unitName` string — Unit name for the value
  - `tierServed` 'raw' | 'hourly' | 'daily' — Storage tier the server actually read from. May differ from the requested tier (e.g. `auto` resolves to a concrete tier; an unsupported tier downgrades to `raw`).
  - `aggregated` boolean — `true` when rows carry aggregate columns (avg/min/max). Set when the response is served from a hourly/daily tier or when `maxDataPoints` triggered on-the-fly bucketing on the raw tier.
  - `bucketSize` integer — On-the-fly bucket size in milliseconds. Only present when the raw tier was bucketed via `maxDataPoints`.
  - `values` object[]
    - `timestamp` string, date-time
    - `value` string — Raw data value (only when `tierServed=raw` and no `maxDataPoints` bucketing).
    - `avg` number — Average value of the bucket. Present for `function=avg` / `function=minmax` tier reads and for on-the-fly raw bucketing.
    - `min` number — Minimum value of the bucket. Present for `function=min` / `function=minmax` tier reads and for on-the-fly raw bucketing.
    - `max` number — Maximum value of the bucket. Present for `function=max` / `function=minmax` tier reads and for on-the-fly raw bucketing.
    - `sampleCount` integer — Number of raw samples that contributed to the bucket. Only populated when reading from a hourly/daily tier.

## Other responses

- `400` — Object is not data collection target or DCI type not supported
- `401` — Unauthorized
- `403` — User does not have read access to given object
- `404` — Object or DCI with given ID does not exist
- `500` — Database failure

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/ee1f54ee3abd/schema)