Write Multi-Value Data Points via mput API for Batch Ingestion - Time Series Database

Writes multi-value data points to Time Series Database (TSDB) using the /api/mput endpoint. Each data point belongs to a single data source at a specific timestamp and carries values across multiple metric fields—for example, cpu, mem, and load for a server—in one write operation.

How it works

A multi-value data point groups several metric field values under one metric name, one timestamp, and one set of tags. This differs from the single-value model (/api/put), where each field requires a separate data point.

All requests use POST /api/mput with a JSON array in the request body. Choose a write mode by adding query parameters to the URL:

Write mode	Query parameter	Returns
Simple	_(none)_	Status code only
Statistical	`summary`	`success`, `failed` counts
Detailed	`details`	`success`, `failed`, `errors` (first failure)
Fault-tolerant	`ignoreErrors`	`success`, `failed`, `errors` (all failures)

Prerequisites

Before you begin, ensure that you have:

Network access to the TSDB HTTP endpoint
At least one tag key-value pair for each data point

In the High-availability Edition, metric names can be up to 255 bytes in length.

Write multi-value data points

Send a POST request to /api/mput with a JSON array of data points in the request body. Each data point must include metric, timestamp, fields, and tags.

Request

Endpoint

POST /api/mput

Query parameters

Add these parameters to the URL to control the response format. An untyped parameter is true when present, regardless of any value you assign to it.

Parameter	Type	Default	Description	Example
`summary`	Untyped	false	Returns write statistics (`success` and `failed` counts).	`/api/mput?summary`
`details`	Untyped	false	Returns write statistics and the first write error. When both `summary` and `details` are present, `details` takes precedence.	`/api/mput?details`
`sync_timeout`	Integer	0	Timeout in milliseconds. `0` means no timeout.	`/api/mput?sync&sync_timeout=60000`
`ignoreErrors`	Untyped	false	Continues writing remaining data points when one fails.	`/api/mput?ignoreErrors`

Request body

Pass a JSON array where each element is a data point with these fields:

Field	Type	Required	Constraints	Description
`metric`	String	Yes	Letters, digits, and `-_./():,[]='#`. Up to 255 bytes in the High-availability Edition.	The metric name.
`timestamp`	Long	Yes	See Timestamp rules.	The data point timestamp, in seconds or milliseconds.
`fields`	Map	Yes	Field names follow the same character rules as `metric`. Values must be STRING, NUMBER, or BOOLEAN. STRING values can be up to 20 KB.	Key-value pairs of metric fields.
`tags`	Map	Yes	Letters, digits, and `-_./():,[]='#`. At least one tag key-value pair required. Non-string values are converted to STRING automatically.	Tag key-value pairs for the data point.

Example request

POST /api/mput
Content-Type: application/json

[
  {
    "metric": "wind",
    "fields": {
      "speed": 20.8,
      "level": 4,
      "direction": "East",
      "description": "Fresh breeze"
    },
    "tags": {
      "sensor": "IOTE_8859_0001",
      "city": "hangzhou",
      "province": "zhejiang",
      "country": "china"
    },
    "timestamp": 1346846400
  },
  {
    "metric": "wind",
    "fields": {
      "speed": 40.2,
      "level": 6,
      "direction": "South",
      "description": "Fresh breeze"
    },
    "tags": {
      "sensor": "IOTE_8859_0002",
      "city": "hangzhou",
      "province": "zhejiang",
      "country": "china"
    },
    "timestamp": 1346846401
  }
]

Timestamp rules

TSDB determines the timestamp unit from the numeric value. These rules apply to /api/put, /api/mput, /api/query, and /api/mquery.

Value range	Unit	Corresponding date range
4,294,968 – 4,294,967,295	Seconds	1970-02-20 01:02:48 – 2106-02-07 14:28:15
4,294,967,296 – 9,999,999,999,999	Milliseconds	1970-02-20 01:02:47.296 – 2286-11-21 01:46:39.999
Outside both ranges	Invalid	—

Write modes

Choose a write mode based on how much response detail your application needs.

Simple mode

No query parameters required. Returns HTTP 204 on success. On failure, returns an error code and error message.

Use this mode for general monitoring data where write errors are not expected and retry logic is handled externally.

Statistical mode

Add ?summary to the request URL. Returns success and failed counts regardless of write outcome.

{
  "success": 20,
  "failed": 0
}

Response field	Type	Description
`success`	Integer	Number of data points written. Counted using the single-value model: each field in a multi-value data point is counted separately.
`failed`	Integer	Number of data points that failed.

In statistical mode, all data points in a single api/mput request either succeed or fail together. If any data point fails, failed reflects the total number of data points in the request.

Use this mode when you need to track write throughput statistics.

Detailed mode

Add ?details to the request URL. Extends statistical mode by including the first write failure in the response.

Response field	Type	Description
`success`	Integer	Number of data points written.
`failed`	Integer	Number of data points that failed.
`errors`	Array	Details of the first data point that failed, including the data point and the failure cause.

In detailed mode, all data points in the request succeed or fail together. The errors array contains only the first failure. Check failed for the total failure count.

Use this mode when you need to identify the cause of a write failure.

Fault-tolerant mode

Add ?ignoreErrors to the request URL. Writes each data point independently—a failure in one does not block the others.

Response field	Type	Description
`success`	Integer	Number of data points written.
`failed`	Integer	Number of data points that failed.
`errors`	Array	All failed data points, each with the data point and its failure cause. Data points not listed in `errors` were written successfully.

Returns HTTP 200 if at least one data point was written. Returns a non-200 status code only if all data points fail due to a critical error such as an underlying storage failure.

Use this mode when your request may contain a mix of valid and invalid data points and you want to maximize the number of successfully written data points.

API differentiation

Use the correct endpoint for each operation:

Operation	Endpoint
Write single-value data points	`POST /api/put`
Write multi-value data points	`POST /api/mput`
Query single-value data points	`GET /api/query`
Query multi-value data points	`GET /api/mquery`