edit-icon download-icon

Write data

Last Updated: Jul 23, 2018

Request path and method

Path Method Description
/api/put POST Writes multiple data points at a time

Request parameters

Name Type Required Description Default value Example
summary Untyped No Whether to return the summary false /api/put?summary
details Untyped No Whether to return the details false /api/put?details
sync_timeout Integer No Timeout, in millisecond (ms). “0” indicates the request never times out. 0 /api/put/?sync&sync_timeout=60000

Note:

  • The value of the untyped parameters is deemed to be “true” as long as they are provided, for example, both “summary=false” and “summary=true” are treated as “summary=true”.
  • If “details” and “summary” are set at the same time, the API returns the “details”.

Request content

The data point is in JSON format. The following table describe the attributes:

Name Type Required Restrictions Description Example
metric String Yes Can only contain English letters (case in-sensitive), Chinese characters, numbers, and special characteristics, such as -_./():,[]=# Stored metric name sys.cpu
timestamp Long Yes None Timestamp in seconds or milliseconds. For details about how to judge the unit, see Timestamp description below. 1499158925
value Long, Double, String, Boolean Yes None Value of the data point 42.5, true
tags Map Yes Can contain English letters (case in-sensitive), Chinese characters, numbers, and special characteristics, such as -_./():,[]=# The tag key-value pair. At least one tag key-value pair is required. {“host”:”web01”}

Timestamp Description

This description is only applicable to the data read/write (/api/put) and data query (api/query) APIs.

The timestamp unit is second or millisecond.TSDB judges the time unit by the numeric value according to the following rules:

  • When the timestamp range is [4284768,9999999999]: the unit is second, and the time range is [1970-02-20 00:59:28, 2286-11-21 01:46:39].
  • When the timestamp range is [10000000000,9999999999999]: the unit is millisecond, and the time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].
  • When the timestamp range is (-∞,4284768) or (9999999999999,+∞): the time range is [1970-04-27 01:46:40.000, 2286-11-21 01:46:39.999].

Example of data writing request

Request: POST/api/put

Body:

  1. [
  2. {
  3. "metric": "sys.cpu.nice",
  4. "timestamp": 1346846400,
  5. "value": 18,
  6. "tags": {
  7. "host": "web01",
  8. "dc": "lga"
  9. }
  10. },
  11. {
  12. "metric": "sys.cpu.nice",
  13. "timestamp": 1346846400,
  14. "value": 9,
  15. "tags": {
  16. "host": "web02",
  17. "dc": "lga"
  18. }
  19. }
  20. ]

Response Description

If the data writing request succeeds at all data points, the error code 204 is returned. If the data writing request fails at some data points, the error code 400 is returned and the response content contains the error details.

If the request parameter contains summary or details, the returned information contains the following attributes:

Name Data type Description
success Integer Number of data points to which the data is successfully written
failed Integer Number of data points to which the data fails to be written
errors Array An array which indicates to which data points the data fails to be written and the cause. It is valid only when the parameter “details” is specified.

Response example

Response example when “summary” is specified:

Request: POST/api/put?summary

Body:

  1. [
  2. {
  3. "metric": "sys.cpu.nice",
  4. "timestamp": 1346846400,
  5. "value": 9,
  6. "tags": {
  7. "host": "web02",
  8. "dc": "lga"
  9. }
  10. }
  11. ]

Response content:

  1. {
  2. "failed": 1,
  3. "success": 0
  4. }

It indicates that no time point succeeded in data writing, and one time point failed in data writing.

Response example when “details” is specified:

Request: POST/api/put?details

Body:

  1. [
  2. {
  3. "metric": "sys.cpu.nice",
  4. "timestamp": 1365465600,
  5. "value": "NaN",
  6. "tags": {
  7. "host": "web01"
  8. }
  9. }
  10. ]

Response content:

  1. {
  2. "errors": [
  3. {
  4. "datapoint": {
  5. "metric": "sys.cpu.nice",
  6. "timestamp": 1365465600,
  7. "value": "NaN",
  8. "tags": {
  9. "host": "web01"
  10. }
  11. },
  12. "error": "Unable to parse value to a number"
  13. }
  14. ],
  15. "failed": 1,
  16. "success": 0
  17. }

It indicates that no time point succeeded in data writing, and one time point failed in data writing. The failed data point is specified by “datapoint”. The cause for the writing failure is specified by the “error” field.

Thank you! We've received your feedback.