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.