Use the HTTP API to write data to TSDB for InfluxDB - Time Series Database

The HTTP API is the primary way to write data to Time Series Database (TSDB) for InfluxDB®. Send POST requests to the /write endpoint using any HTTP client, including curl.

Note

All examples on this page use curl. curl is a command-line tool that transfers data using URLs.

Prerequisites

Before you begin, ensure that you have:

A TSDB for InfluxDB® instance
A database created in the instance (examples on this page use a database named mydb)
The domain name, account name, and password for the instance

Line protocol

Data is written in line protocol format. Each line represents one data point and consists of up to four elements:

Element	Required	Data type	Description
Measurement	Yes	String	The name of the measurement. Each data point belongs to exactly one measurement.
Tag set	No	String keys and string values	Key-value pairs that identify the data source. Tags are indexed, which makes queries faster and more efficient.
Field set	Yes	String keys; FLOAT values by default	Key-value pairs that store the actual data. At least one field is required per data point.
Timestamp	No	Unix timestamp (nanoseconds)	The time of the data point, in nanoseconds elapsed since 00:00:00 UTC on January 1, 1970. If omitted, TSDB for InfluxDB® uses the server timestamp at the time of write. All timestamps use UTC+0.

Line protocol syntax:

<measurement>[,<tag_key>=<tag_value>...] <field_key>=<field_value>[,<field_key>=<field_value>...] [<timestamp>]

Example:

cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000

This line writes one data point to the cpu_load_short measurement with:

Tag set: host=server01, region=us-west
Field set: value=0.64
Timestamp: 1434055562000000000

Write a single data point

Send a POST request to /write with the data point in the request body:

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'

Replace the following placeholders:

Placeholder	Description	Example
`<domain-name>`	Domain name of the TSDB for InfluxDB® instance	`tsdb-xxx.influxdata.aliyuncs.com`
`<account-name>`	Username of the account created for the instance	`admin`
`<password>`	Password of the account	`MyPassword`

Important

Always use --data-binary when sending line protocol data with curl. Options like -d, --data-urlencode, and --data-ascii may strip newlines or alter formatting, which causes write failures.

For a full list of query parameters, see Query parameters. For complete API documentation, see HTTP API Reference.

Write multiple data points

Separate multiple data points with newlines in a single POST request. Batching data points reduces network overhead and improves write performance.

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'

This request writes three data points to the cpu_load_short measurement:

The first data point has the tag host=server02 and no timestamp, so TSDB for InfluxDB® assigns the server timestamp.
The second data point has the tag set host=server02,region=us-west and the timestamp 1422568543702900257.
The third data point has the tag set direction=in,host=server01,region=us-west and the same timestamp as the second data point.

Write data from a file

Pass @<filename> to curl to write data points from a file. The file must contain valid line protocol, one data point per line.

Example file (`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

Write the file to `mydb`:

curl -i -XPOST 'https://<domain-name>:3242/write?db=mydb&u=<account-name>&p=<password>' \
  --data-binary @cpu_data.txt

Note

HTTP requests time out after 5 seconds by default. If the file contains more than 5,000 data points, split it into smaller files and write them in batches to avoid timeout errors.

Query parameters

Parameter	Required	Description
`db=<database>`	Yes	The target database for the write.
`u=<username>`	Yes	The username for authentication.
`p=<password>`	Yes	The password for authentication.
`rp=<retention_policy>`	No	The target retention policy. Writes to the default retention policy if not specified.

Schemaless design

TSDB for InfluxDB® uses a schemaless design. Add new measurements, tags, and fields at any time without modifying a schema.

Warning

TSDB for InfluxDB® rejects data points that write a different data type to an existing field. For example, writing a string to a field that already stores integers returns an error. Make sure field value types are consistent across all writes to the same field.

HTTP response codes

Status code	Meaning	Common causes
`204 No Content`	Write successful	—
`400 Bad Request`	Request could not be parsed	Line protocol syntax error; field type conflict (writing a different data type to an existing field)
`404 Not Found`	Resource not found	Writing to a database that does not exist
`5xx`	System is overloaded or severely damaged	—

Error response examples:

Writing a float to a field that stores Boolean values:

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'

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

Writing 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'

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

Usage notes

REST compliance: TSDB for InfluxDB® uses HTTP as the transport protocol but does not fully conform to RESTful standards. It provides three API endpoints and transfers InfluxQL statements over HTTP.

Default port: TSDB for InfluxDB® uses port 3242 by default.

What's next

Query the data you wrote: Use the HTTP API to query data
Explore all write endpoint options: HTTP API Reference

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