The InfluxDB API provides a simple way interact with the database. It uses HTTP response codes, HTTP authentication, JWT Token, and basic authentication and responses are returned in JSON.

The following sections assume your InfluxDB instance is running on localhost port 8086 and HTTPS is not enabled.

Endpoints

Endpoint Description
/ping use /ping to check the status of your InfluxDB instance and your version of InfluxDB
/query use /query to query data and manage databsae, retention policies and users
/write use /write to write data to a pre-exising databse

/ping

The ping endpoint accepts both GET and POST HTTP requests. Use this endpoint to check the status of your InfluxDB instance and your version of InfluxDB.

Definition

1
2
3
GET http://localhost:8086/ping

HEAD http://localhost:8086/ping

Example

Extract the version of your InfluxDB instance in the X-Influxdb-Version field of the header

1
2
3
4
5
6
7
$ curl -sl -I localhost:8086/ping

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.2.x
Date: Wed, 01 Mar 2017 00:09:51 GMT

Status Codes and Responses

The response body is empty

HTTP Status Code Description
204 Success! Your InfluxDB instance is up and running

/query

The /query endpoint accepts GET and POST HTTP requests. Use this endpoint to query data and manage databases, retention policies, and users.

Definition

1
2
3
GET http://localhost:8086/query

POST http://localhost:8086/query

Verb usage

verb Query Type
GET use for all queries that start with SETECT, SHOW
POST use for all queries that start with ALTER, CREATE, DELETE, DROP, GRANT, KILL, REVOKE

THe only exceptions are SELECT queries that include an INTO clause. Those SELECT queries require a POST request.

Example

Example 1: Query data with a SELECT statement
1
2
3
curl -G 'http://localhost:8086/query?db=mydb' --data-urlencoded 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

The mymeas measurement has two points. The first point has the timestamp 2017-03--1T00:15:18Z, a myfield value of 33.1 and no tag values for the mytag1 and mytag2 tag keys.

The second point has the timestamp 2017-03--1T00:18:18Z, a myfield value of 12, a mymeas value of 12, a mytag1 value of 12 and a mytag2 value of 14

The same query in InfluxDB’s Command Line Interface(CLI) returns the following table:

1
2
3
4
5
name: mymeas
time                   myfield   mytag1   mytag2
----                   -------   ------   ------
2017-03--1T00:15:18Z    33.1
2017-03--1T00:18:18Z    12        12       14
Example 2: Query data with a SELECT statement and an INTO clause
1
curl -XPOST 'http://localhost:8086/query?db=mydb' --data-urlencoded 'q=SELECT * INTO "newmeas" FROM "mymeas"'

SELECT queries that include and INTO clause require a POST requests

Example 3: Create a database
1
curl -XPOST 'http://localhost:8086/query' --data-urlencoded 'q=CREATE DATABASE "mydb"'

A successful CREATE DATABASE query returns no additional information.

Query String Parameter

1
Query String Parameter         |                                            Optional/Required                                             |                                                                                Definition

:———————————–: | :——————————————————————————————————: | :———————————————————————————————————————————————————————–: chunked=[true | <number_of_points] | Optional | Returns points in streamed batches instead of in a single response. If set to true, InfluxDB chunks responses by series or by every 10,000 point, whichever occurs first. It set to a specific value, InfluxDB chunks responses by series or by that number of points db=

| Required for database-dependent queries(most SELECT queries and SHOW queries require this parameter) | Sets the target database for the query epoch=[ns,u,ms,s,m,h] | Optional | Returns epoch timestamps with the specified precision. By default, InfluxDB returns timestamps in RFC3339 format with nanosecond precision. Both u indicate microsecond p=

| Optional if you haven’t enabled authentication. Required if you’ve enabled authentication | Sets the password for authentication if you’ve enabled authentication. Use with the query string parameter u pretty=true | Optional | Enables pretty-printed JSON output. While this is useful for debugging it is not recommended for production use as it consumes unnecessary network bandwidth u=

| Optional if you haven’t enabled authentication. Required if you’ve enabled authentication | Sets the username for authentication if you’ve enabled authentication. The user must have read access to the database. Use with the query string parameter p

In versions 1.2.0 and 1.2.1, InfluxDB automatically truncates the number of rows returned for requests without the chunked parameter. By default, the maximum number of rows returned is set to 10000, if a query has more than 10000 rows to return, InfluxDB includes a 'partial': true tag in the response body.

The HTTP API also supports basic authentication. Use basic authentication if you’ve enabled authentication and aren’t using the query string parameter u and p.

Example: Create a database using HTTP authentication
1
curl -XPOST 'http://localhost:8086/query?u=myusername&p=mypassword' --data-urlencoded 'q=CREATE DATABASE "mydb"'

/write

The /write endpoint accepts POST HTTP requests. Use this endpoint to write data to a pre-existing databse.

Definition

1
POST http://localhost:8086/write

Query String Parameter

           Query String Parameter                 | Optional/Required                                                                         | Description

:—————————————————: | :—————————————————————————————- | :————————————————————————————————————————————————————–
consistency=[any | one | quorum | all] | Optional, available with InfluxEnterprise clusters only | Sets the write consistency for the point. InfluxDB assumes that the write consistency is one if you do not specify consistency
db=

| Required | Sets the target database for the write p= | Optional if you haven't enabled authentication. Required if you've enabled authentication | Sets the password for authentication if you've enabled authentication. Use with the query string parameter `u` precision=[ns,u,ms,m,h] | Optional | Sets the precision for the supplied Unix time values. InfluxDB assumes that timestamps are in nanoseconds if you do not specify `precision` rp= | Optional | Sets the target retention policy for the write. InfluxDB writes to the `DEFAULT` retention policy if you do not specify a retention policy u= | Optional if you haven't enabled authentication. Required if you've enabled authentication | Sets the username for authentication if you've enabled authentication. The user must have write access to the database. Use with the query string parameter `p`