Write data - Developer Guide| Alibaba Cloud Documentation Center

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:

[
    {
        "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"
        }
    }
]

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:

[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        }
  }
]

Response content:

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

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:

    [
        {
                      "metric": "sys.cpu.nice",
                      "timestamp": 1365465600,
                      "value": "NaN",
                      "tags": {
                          "host": "web01"
                      }
        }
    ]

Response content:

    {
        "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
    }

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.