All Products
Search
Document Center

Use the HTTP API to write data

Last Updated: May 29, 2020

You can use several methods to write data to TSDB for InfluxDB®, such as the command-line interface (CLI) and clients. This topic describes how to use the embedded HTTP API to write data.

Note: The examples in this topic are based on curl, which is a command-line tool that uses URLs to transmit data.

The primary means to write data to TSDB for InfluxDB® is to send POST requests to the /write endpoint by using the HTTP API. Assume that the mydb database is created. This topic describes how to write data to the mydb database by using the HTTP API.

Write a single point to the database

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

 
  1. curl -i -XPOST 'https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'

In the preceding example, replace Domain name with the domain name of your TSDB for InfluxDB® instance, and replace Username and Password with the actual username and password. By default, TSDB for InfluxDB® uses the 3242 port. When you write data, set db to an existing database. If you do not set a retention policy by specifying rp, the data will be written to the db database based on the default retention policy. For more information about parameters, see HTTP API.

The body of a POST request contains the time series data that you want to write. The body must use the line protocol syntax and include the measurement, tags, fields, and timestamp of a point. A point to be written to TSDB for InfluxDB® must contain a measurement. Tags are optional. However, most points contain tags, which are used to identify data sources and enable simple and efficient data queries. Tag keys and tag values must be strings. Field keys are required and must be strings. By default, field values are floats. The number at the end of the command line is the timestamp. It is a UNIX timestamp that represents the number of nanoseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 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 point. Timestamps in TSDB for InfluxDB® use the UTC+0 time zone.

Write multiple points

You can use a line break to separate points and send them to multiple time series at the same time. This improves the data writing performance.

The following example describes how to write three points to the mydb database. The first point belongs to the time series that has the cpu_load_short measurement and the host=server0 tag. This point uses the timestamp of the location where the instance resides. The second point belongs to the time series that has the cpu_load_short measurement and the host=server02,region=us-west tags. The timestamp is 142256854370290025. The third point belongs to the time series that has the cpu_load_short measurement and the direction=in,host=server01,region=us-west tags. The timestamp is the same as that of the second point.

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

Write a file to TSDB for InfluxDB®

You can write points in a file to TSDB for InfluxDB® by using @filename in a curl command. Data in the file must be organized in the line protocol syntax.

The following example is the cpu_data.txt file that complies with the line protocol syntax.

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

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

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

Note: By default, an HTTP request times out after five seconds. If a file contains a large number of points, TSDB for InfluxDB® may fail to write the remaining 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 points, split the file into multiple files and write the file data to TSDB for InfluxDB® in batches.

Schemaless database design

TSDB for InfluxDB® provides schemaless databases. You can add measurements, tags, and fields as required. If you attempt to write data of a different type, TSDB for InfluxDB® may reject the data. For example, you cannot write a string to a field that consists of integers.

REST

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

Modern web APIs are designed based on Representational State Transfer (REST) because it resolves a common issue. As the number of endpoints grows, the need for an organizing system becomes pressing. REST is the industry agreed style for organizing large numbers of endpoints. REST benefits both API developers and customers, because everyone involved 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 InfluxQL statements. APIs in TSDB for InfluxDB® do not fully conform to RESTful standards.

HTTP status codes

  • 2xx: After you send a write request, if HTTP 204 No Content is returned, data is written to TSDB for InfluxDB®.
  • 4xx: TSDB for InfluxDB® fails to parse the request.
  • 5xx: TSDB for InfluxDB® is overloaded or significantly impaired.

Examples of error responses:

  • If you write a float to a Boolean field:
 
  1. curl -i -XPOST 'https://<Domain name>:3242/write?db=<Database name>&u=<Username>&p=<Password>' --data-binary 'tobeornottobe booleanonly=true'
  2. curl -i -XPOST 'https://<Domain name>:3242/write?db=<Database name>&u=<Username>&p=<Password>' --data-binary 'tobeornottobe booleanonly=5'

The system returns:

 
  1. HTTP/1.1 400 Bad Request
  2. Content-Type: application/json
  3. Request-Id: [...]
  4. X-Influxdb-Version: 1.7.x
  5. Date: Wed, 01 Mar 2017 19:38:01 GMT
  6. Content-Length: 150
  7. {"error":"field type conflict: input field \"booleanonly\" on measurement \"tobeornottobe\" is type float, already exists as type boolean dropped=1"}
  • If you write data to a database that does not exist:
 
  1. curl -i -XPOST 'https://<Domain name>:3242/write?db=atlantis&u=<Username>&p=<Password>' --data-binary 'liters value=10'

The system returns:

 
  1. HTTP/1.1 404 Not Found
  2. Content-Type: application/json
  3. Request-Id: [...]
  4. X-Influxdb-Version: 1.7.x
  5. Date: Wed, 01 Mar 2017 19:38:35 GMT
  6. Content-Length: 45
  7. {"error":"database not found: \"atlantis\""}

Next steps

After you understand how to use the embedded HTTP API to write data to TSDB for InfluxDB®, you can learn how to read 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.


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