Write Batch Data Points to TSDB via POST /api/put - Time Series Database

Use POST /api/put to write one or more data points to Time Series Database (TSDB) in a single request.

Quick start

The following example writes two data points using curl. Replace the placeholder values before running.

curl -X POST 'http://<your-tsdb-endpoint>/api/put?summary' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "metric": "sys.cpu.nice",
      "timestamp": 1346846400,
      "value": 18,
      "tags": {"host": "web01", "dc": "lga"}
    },
    {
      "metric": "sys.cpu.nice",
      "timestamp": 1346846400,
      "value": 9,
      "tags": {"host": "web02", "dc": "lga"}
    }
  ]'

Placeholder	Description	Example
`<your-tsdb-endpoint>`	Your TSDB instance address	`tsdb.example.com:4242`

Endpoint

Request path	Request method	Description
`/api/put`	POST	Writes multiple data points at a time

Query parameters

Append these parameters to the request URL to control the response format.

Parameter	Type	Required	Default	Description	Example
`summary`	Untyped	No	false	Returns the count of successful and failed writes	`/api/put?summary`
`details`	Untyped	No	false	Returns the count plus error details for failed data points	`/api/put?details`
`sync_timeout`	Integer	No	0	Timeout in milliseconds. `0` means no timeout.	`/api/put?sync&sync_timeout=60000`
`ignoreErrors`	Untyped	No	false	Continues writing remaining data points when one fails	`/api/put?ignoreErrors`

For untyped parameters, the system treats the parameter as true whenever it appears in the URL, regardless of the value assigned. For example, both ?summary=true and ?summary=false activate summary mode. If you specify both details and summary, the API returns details.

Request body

Specify data points as a JSON array. Each element represents one data point.

Parameter	Type	Required	Constraint	Description	Example
`metric`	String	Yes	Letters, digits, and `-` `_` `.` `/` `(` `)` `:` `,` `[` `]` `=` `'` `#`	The metric name	`sys.cpu.nice`
`timestamp`	Long	Yes	See Timestamp rules	Unix timestamp in seconds or milliseconds	`1346846400`
`value`	Long, Double, String, Boolean	Yes	String values cannot exceed 20 KB	The data point value	`18`, `"High CPU Load"`, `true`
`tags`	Map	No	Same character set as `metric`; at least one key-value pair required	Tag key-value pairs	`{"host": "web01", "dc": "lga"}`

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

Tags that are not of the String type are automatically converted to String.

Timestamp rules

TSDB automatically determines whether a timestamp is in seconds or milliseconds based on its numeric value. The same rules apply to both /api/put and /api/query.

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 and responses

By default, POST /api/put returns HTTP 204 with no body if all data points are written successfully. Add query parameters to get additional response detail or to isolate individual write failures.

Simple mode (default)

Send the request with no mode parameters.

Success: HTTP 204, no response body
Failure: HTTP error code and error message

Use this mode for general monitoring data where minimal overhead is needed.

Statistical mode

Add ?summary to get a count of successes and failures.

POST /api/put?summary

Response parameters:

Parameter	Type	Description
`success`	Integer	Number of data points written successfully
`failed`	Integer	Number of data points that failed to write

Example response:

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

Important

In statistical mode, all data points in a single request either succeed or fail together. If any write fails, failed equals the total number of data points in the request.

Use this mode when you need to track how many data points were accepted.

Detailed mode

Add ?details to get error information alongside the success and failure counts. Detailed mode is an extension of statistical mode.

POST /api/put?details

Response parameters:

Parameter	Type	Description
`success`	Integer	Number of data points written successfully
`failed`	Integer	Number of data points that failed to write
`errors`	Array	The first failed data point and its failure cause

Example response:

{
  "errors": [
    {
      "datapoint": {
        "metric": "sys.cpu.nice",
        "timestamp": 1365465600,
        "value": "NaN",
        "tags": {"host": "web01"}
      },
      "error": "Unable to parse value to a number"
    }
  ],
  "failed": 1,
  "success": 0
}

Important

In detailed mode, all data points in a single request either succeed or fail together. The errors array contains only the first failed data point. To see how many data points failed, check the failed parameter.

Use this mode when you need to locate write failures.

Fault-tolerant mode

Add ?ignoreErrors to allow the request to continue writing remaining data points when one fails.

POST /api/put?ignoreErrors

Response parameters:

Parameter	Type	Description
`success`	Integer	Number of data points written successfully
`failed`	Integer	Number of data points that failed to write
`errors`	Array	Each failed data point and its failure cause

Important

Unlike statistical and detailed modes, fault-tolerant mode does not treat the request atomically — a failure in one data point does not affect the others. The errors array contains every failed data point, not just the first. Data points not listed in errors were written successfully.

If some (but not all) data points fail: HTTP 200
If all data points fail due to a critical error (such as underlying storage failure): non-200 status code

Use this mode when you need to maximize the number of data points written and handle individual failures separately.

Limitations

Maximum tag keys per time series

The maximum number of tag keys in a single time series depends on the instance type.

Instance type	Maximum tag keys
mLarge	16
Large	16
3xLarge	20
4xLarge	20
6xLarge	20
12xLarge	20
24xLarge	24
48xLarge	24
96xLarge	24

String values

String values can contain any characters and can be stored in JSON format. The maximum size of a string value is 20 KB.