All Products
Search
Document Center

Time Series Database:Use the HTTP API to write data

Last Updated:Nov 17, 2021

You can use multiple methods, such as the CLI and client libraries, to write data to Time Series Database (TSDB) for InfluxDB®. This topic describes how to use the built-in HTTP API to write data.

Note

In the examples provided in this topic, the curl tool is used. The curl tool is a CLI that uses URLs to transmit data.

The HTTP API is the primary method that is used to write data to TSDB for InfluxDB®. To use the HTTP API to write data, send POST requests to the /write endpoint. Before you write data, create a database in your TSDB for InfluxDB® instance. In this topic, a database named mydb is created and used. The following sections describe how to use the HTTP API to write data to mydb.

Write a single data point

The following example shows how to write a single data point to the mydb database. The data point contains the cpu_load_short measurement and two tags. The tag keys are host and region. The corresponding tag values are server01 and us-west. The field key is value, and the field value is 0.64. The timestamp is 1434055562000000000.

curl -i -XPOST 'https://<Domain name>:3242/write?db=mydb&u=<Account name>&p=<Password>' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
  • <Domain name> specifies the domain name of your TSDB for InfluxDB® instance.

  • <Account name> and <Password> specify the username and password of the account that you created for the TSDB for InfluxDB® instance.

  • By default, TSDB for InfluxDB® uses port 3242.

  • When you write a data point, you must use the db parameter to specify an existing database. If you do not use the rp parameter to configure a data retention policy, the data point is written based on the default data retention policy of the database that is specified by the db parameter.

For a complete list of request parameters, see HTTP API Reference.

The body of a POST request contains the time series data point that you want to store in the line protocol format. The body consists of a measurement, tags, fields, and a timestamp. A measurement must be specified for a time series data point in TSDB for InfluxDB®. Tags are optional, but most time series data points contain tags that are used to identify the source of data. This makes queries simple and efficient. Tag keys and tag values must be strings. Field keys are required and must be strings. The default data type of field values is FLOAT. The timestamp is specified at the end of the line in the UNIX time format. The value of a timestamp is in nanoseconds and indicates the time that has elapsed since 00:00:00 Thursday, 1 January, 1970 UTC. The timestamp is optional. If you do not specify a timestamp, TSDB for InfluxDB® uses the UNIX timestamp of the location where the instance is deployed as the timestamp of the data point. Timestamps in TSDB for InfluxDB® use the UTC+0 time zone.

Write multiple data points

You can specify multiple data points in one POST request and separate them with line feeds. This way, multiple data points are sent to multiple time series at the same time. This can improve the performance of your database.

The following example shows how to use one POST request to write three data points to the mydb database:

  • The first data point belongs to the time series that has the cpu_load_short measurement and the host=server0 tag. This data point uses the timestamp of the location where the instance resides.

  • The second data point belongs to the time series that has the cpu_load_short measurement and the host=server02,region=us-west tag set. The timestamp is 142256854370290025.

  • The third data point belongs to the time series that has the cpu_load_short measurement and the direction=in,host=server01,region=us-west tag set. The timestamp is the same as that of the second data point.

curl -i -XPOST 'https://<Domain name>:3242/write?db=mydb&u=<Account name>&p=<Password>' --data-binary 'cpu_load_short,host=server02 value=0.67
cpu_load_short,host=server02,region=us-west value=0.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=2.0 1422568543702900257'

Write data points from a file

You can write data points from a file to TSDB for InfluxDB® by passing @filename to curl. The data in the file must follow the line protocol syntax.

The following code provides an example of a file that complies with the line protocol syntax. The file is named cpu_data.txt.

cpu_load_short,host=server02 value=0.67
cpu_load_short,host=server02,region=us-west value=0.55 1422568543702900257
cpu_load_short,direction=in,host=server01,region=us-west value=2.0 1422568543702900257

Run the following command to write the data in the cpu_data.txt file to the mydb database:

curl -i -XPOST 'https://<Domain name>:3242/write?db=mydb&u=<Account name>&p=<Password>' --data-binary @cpu_data.txt
Note

By default, an HTTP request times out after 5 seconds. If a file contains a large number of data points, TSDB for InfluxDB® may fail to write the remaining data points after the request times out. In this case, we recommend that you split the file. For example, if a file contains more than 5,000 data points, split the file into multiple files and write the file data to TSDB for InfluxDB® in batches.

Schemaless design

TSDB for InfluxDB® provides schemaless databases. You can add new measurements, tags, and fields based on your business requirements.

Notice

If you attempt to write data points that use a different data type than the data points that are stored, TSDB for InfluxDB® rejects these data points. For example, strings cannot be written to a field in which integers are written.

Usage notes on REST

TSDB for InfluxDB® uses the widely used HTTP protocol to transmit data.

Modern web APIs are based on the representational state transfer (REST) architecture because REST solves the following common issue: When the number of endpoints increases, the need for an organizing system becomes pressing. REST is an industry-acknowledged standard for organizing large numbers of endpoints. The use of a consistent standard in the industry provides benefits for developers and consumers of APIs because every participant knows what to expect.

However, REST is only a convention. TSDB for InfluxDB® is a simple and easy-to-use system that provides only three API endpoints and uses HTTP to transfer InfluxQL statements. APIs in TSDB for InfluxDB® do not fully conform to RESTful standards.

HTTP response summary

  • 2xx: If an HTTP 204 No Content message is returned for a write request, the data is written to TSDB for InfluxDB®.

  • 4xx: TSDB for InfluxDB® fails to parse the request.

  • 5xx: The system is overloaded or severely damaged.

The following part provides sample error responses:

  • Write a floating-point number to a field in which Boolean values are stored.

curl -i -XPOST 'https://<Domain name>:3242/write?db=<Database name>&u=<Account name>&p=<Password>' --data-binary 'tobeornottobe booleanonly=true'

curl -i -XPOST 'https://<Domain name>:3242/write?db=<Database name>&u=<Account name>&p=<Password>' --data-binary 'tobeornottobe booleanonly=5'

The system returns the following response:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 01 Mar 2017 19:38:01 GMT
Content-Length: 150

{"error":"field type conflict: input field \"booleanonly\" on measurement \"tobeornottobe\" is type float, already exists as type boolean dropped=1"}
  • Write data to a database that does not exist.

curl -i -XPOST 'https://<Domain name>:3242/write?db=atlantis&u=<Account name>&p=<Password>' --data-binary 'liters value=10'

The system returns the following response:

HTTP/1.1 404 Not Found
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 01 Mar 2017 19:38:35 GMT
Content-Length: 45

{"error":"database not found: \"atlantis\""}

What to do next

After data is written to a database by using the built-in HTTP API of TSDB for InfluxDB®, you can query the data. For more information, see Use the HTTP API to query data. For more information about how to use the HTTP API to write data, see HTTP API Reference.

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.