All Products
Search
Document Center

Time Series Database:HTTP API

Last Updated:Jul 05, 2023

The HTTP API of Time Series Database (TSDB) for InfluxDB® provides a simple way to interact with databases. This API authenticates requests by using HTTP authentication, JSON Web Tokens (JWT), and basic authentication, and returns HTTP status codes and responses in JSON format.

This topic describes the HTTP API endpoints provided by a TSDB for InfluxDB® instance. The examples assume that the instance runs on and the 3242 port, and HTTPS is enabled.

TSDB for InfluxDB® HTTP API endpoints

Endpoint

Description

/ping

Queries the status and version of the TSDB for InfluxDB® instance.``

/query

Queries data and manages databases, retention policies (RPs), and users.``

/write

Writes data to an existing database.``

/ping HTTP endpoint

The /ping endpoint accepts both GET and HEAD HTTP requests. Use /ping to check the TSDB for InfluxDB® version and instance status.

Definition

GET https://<Domain name>:3242/ping?u=<Username>&p=<Password>
HEAD https://<Domain name>:3242/ping?u=<Username>&p=<Password>

verbose option

By default, the /ping endpoint returns the HTTP 204 status code to notify the client that the server is running. The default value of verbose is false. If verbose is set to true (/ping?verbose=true), the HTTP 200 status code is returned.

Examples

You can use the /ping endpoint to view the version of the TSDB for InfluxDB® instance. The x-Influxdb-Version header field shows the version.

~ curl -sl -I https://<Domain name>:3242/ping?u=<Username>&p=<Password>

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
X-Influxdb-Build: OSS
X-Influxdb-Version: v1.7.x
X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
Date: Tue, 05 Nov 2018 16:08:32 GMT

Status codes and responses

The body of the response is empty.

HTTP status code

Description

204

The request is successful. The TSDB for InfluxDB® instance is running.

/query HTTP endpoint

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

Definition

GET https://<Domain name>:3242/query?u=<Username>&p=<Password>
POST https://<Domain name>:3242/query?u=<Username>&p=<Password>

Verb usage

Verb

Query type

GET

This verb is used for all queries that start with the following keywords:

SELECT

SHOW

POST

This verb is used for all queries that start with the following keywords:

ALTER

CREATE

DELETE

DROP

GRANT

KILL

REVOKE

* The only exceptions are SELECT query statements that include the INTO clause, which require POST requests.

Examples

Run SELECT statements to query data

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode '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. In the first point, the timestamp is 2017-03-01T00:16:18Z, the value of the myfield field key is 33.1, and the mytag1 and mytag2 tag keys have no values. In the second point, the timestamp is 2017-03-01T00:17:18Z, the value of the myfield field key is 12.4, the value of the mytag1 tag key is 12, and the value of the mytag2 tag key is 14.

The same query in the TSDB for InfluxDB® command-line interface (CLI) returns the following table.

name: mymeas
time                  myfield  mytag1  mytag2
----                  -------  ------  ------
2017-03-01T00:16:18Z  33.1
2017-03-01T00:17:18Z  12.4     12      14

Run SELECT statements that include the INTO clause to query data

$ curl -XPOST 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

If you want to run a SELECT statement that includes the INTO clause to query data, POST requests are required.

The response shows that TSDB for InfluxDB® writes two points to the newmeas measurement. The system uses epoch 0 (1970-01-01T00:00:00Z) as an null timestamp.

String query parameters

String query parameters

Optional/Required

Description

chunked=[true, number_of_points]

Optional

Returns points in streamed batches instead of in a single response. If this parameter is set to true, TSDB for InfluxDB® chunks responses by series or by every 10,000 points, whichever occurs first. If you specify a number, TSDB for InfluxDB® chunks responses by series or by the specified number of points.

db=database_name

Required for database-dependent queries (most SELECT and SHOW queries)

Specifies the target database for the query.

epoch=[ns,u,µ,ms,s,m,h]

Optional

Returns the epoch timestamp of the specified accuracy. By default, TSDB for InfluxDB® returns the nanosecond timestamp that follows the RFC 3339 format. Both u and µ indicate microseconds.

p=password

Optional if authentication is not enabled. Required if authentication is enabled.

Specifies the password for authentication if authentication is enabled. This parameter must be used with u.

pretty=true

Optional

Enables pretty-printed JSON output. This is useful for debugging. However, this setting consumes extra network bandwidth. We recommend that you do not enable this option for production.

q=query

Required

The Influx Query Language (InfluxQL) command to run.

u=username

Optional if authentication is not enabled. Required if authentication is enabled.

Specifies the username for authentication if authentication is enabled. The user must have the read permission on databases. This parameter must be used with p.

* If the chunked parameter is not used, TSDB for InfluxDB® does not truncate the rows returned for requests.

Examples

Use SELECT statements to query data and return pretty-printed JSON data

$ curl -G 'https://<Domain name>:3242/query?db=mydb&pretty=true&u=<Username>&p=<Password>' --data-urlencode '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"
                        ]
                    ]
                }
            ]
        }
    ]
}

Use a SELECT statement to query data and return epoch timestamps of accuracies other than nanoseconds.

$ curl -G 'https://<Domain name>:3242/query?db=mydb&epoch=s&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

Request body

--data-urlencode "q=<InfluxQL query>"

All queries must be URL encoded and follow InfluxQL syntax. All examples on this page include the --data-urlencode parameter in the curl commands.``

Options

Send multiple queries

Use semicolons (;) to separate multiple queries.

Submit queries in a file

You can use a multipart POST request to submit queries in a file. The queries in the file must be separated with semicolons (;).

Syntax:

curl -F "q=@<path_to_file>" -F "async=true" https://<Domain name>:3242/query?u=<Username>&p=<Password>

Request query results in CSV format

Syntax:

curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?u=<Username>&p=<Password>' [...]

If a request includes -H Accept: application/csv, the system returns epoch timestamps rather than RFC 3339 timestamps.

Bind parameters

The HTTP API allows you to bind parameters to specified field values or tag values in WHERE clauses. Use the $<placeholder_key> syntax as a placeholder in the query, and URL encode the map of placeholder keys to placeholder values in the request body.

Query syntax:

--data-urlencode 'q= SELECT [...] WHERE [ <field_key> | <tag_key> ] = $<placeholder_key>'

Map syntax:

--data-urlencode 'params={"<placeholder_key>":[ <placeholder_float_field_value> | <placeholder_integer_field_value> | "<placeholder_string_field_value>" | <placeholder_boolean_field_value> | "<placeholder_tag_value>" ]}'

Use commas (,) to separate multiple placeholder key-value pairs.

Examples

Send multiple queries

$ curl -G 'https://<Domain name>:3242/query?db=mydb&epoch=s&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]},{"statement_id":1,"series":[{"name":"mymeas","columns":["time","mean"],"values":[[0,22.75]]}]}]}

The request contains two queries: SELECT * FROM "mymeas" and SELECT mean("myfield") FROM "mymeas". The output shows that the system allocates the statement_id statement identifier to each query returned. The value of statement_id is 0 in the result of the first query. The value of statement_id is 1 in the result of the second query.

Request query results in CSV format

$ curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

name,tags,time,myfield,mytag1,mytag2
mymeas,,1488327378000000000,33.1,mytag1,mytag2
mymeas,,1488327438000000000,12.4,12,14

The first point has no tag values for the mytag1 and mytag2 tag keys.

Submit queries in a file

$ curl -F "q=@queries.txt" -F "async=true" 'https://<Domain name>:3242/query?u=<Username>&p=<Password>'

The following is an example of queries in the queries.txt file:

SELECT * FROM "mymeas";
SELECT mean("myfield") FROM "mymeas";

Bind parameters in the WHERE clause to specified tag values

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value' --data-urlencode 'params={"tag_value":"12"}'

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

The request maps $tag_value to 12. TSDB for InfluxDB® stores tag values as strings. Therefore, the tag values in the request must be enclosed in double quotation marks (“).

Bind parameters in the WHERE clause to numeric field values

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "myfield" > $field_value' --data-urlencode 'params={"field_value":30}'

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

The request maps $field_value to 30. The value 30 does not need to be enclosed in double quotation marks (“) because myfield stores numeric field values.

Bind the two parameters in the WHERE clause to a specified tag value and a numeric field value respectively

$ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value AND  "myfield" < $field_value' --data-urlencode 'params={"tag_value":"12","field_value":30}'

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

The request maps $tag_value to 12 and $field_value to 30.

Status codes and responses

Responses are returned in JSON format. You can include pretty=true to enable pretty-printed JSON output.

Summary

HTTP status code

Description

200 OK

The request is successful. For more information, see the JSON output.

400 Bad Request

The request cannot be processed. This may be caused by incorrect query syntax. For more information, see the JSON output.

401 Unauthorized

The request cannot be processed. This may be caused by invalid credentials for authentication.

Examples

A request that returns data

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:22:54 GMT
Transfer-Encoding: chunked

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

A request that returns an error

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb1&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:23:48 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

A query of an incorrect format

$ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:24:25 GMT
Content-Length: 76

{"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

A query that uses invalid authentication credentials

$ curl -i  -XPOST 'https://<Domain name>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:11:26 GMT
Content-Length: 33

{"error":"authorization failed"}

/write HTTP endpoint

The /write endpoint accepts POST HTTP requests. Use /write to write data to a created database.

Definition

POST https://<Domain name>:3242/write?u=<Username>&p=<Password>

String query parameters

String query parameters

Optional/Required

Description

db=\

Required

Specifies the target database to which data is written.

p=\

Optional if authentication is not enabled. Required if authentication is enabled.

Specifies the password for authentication if authentication is enabled. This parameter must be used with u.

precision=[ns,u,ms,s,m,h]

Optional

Specifies the accuracy of the provided UNIX timestamp. If you do not set this parameter, TSDB for InfluxDB® assumes that the timestamp is accurate to nanoseconds.

rp=\

Optional

Specifies the target RP for the write. If you do not set this parameter, TSDB for InfluxDB® writes data to the default (DEFAULT) RP.

u=\

Optional if authentication is not enabled. Required if authentication is enabled.

Specifies the username for authentication if authentication is enabled. The user must have the write permission on databases. This parameter must be used with p.

** We recommend that the time be accurate to the smallest granularity to significantly improve the compression performance.

Examples

Write a point whose timestamp is accurate to seconds to the mydb database

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&precision=s&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:33:23 GMT

Write a point to the mydb database and the myrp RP

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&rp=myrp&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:31 GMT

Write a point to the mydb database by using HTTP authentication

Valid credentials:

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:56 GMT

Invalid credentials:

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:40:30 GMT
Content-Length: 33

{"error":"authorization failed"}

Write a point to the mydb database by using basic authentication

Valid credentials:

$ curl -i -XPOST -u myusername:mypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:36:40 GMT

Invalid credentials:

$ curl -i -XPOST -u myusername:notmypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

Request body

--data-binary '<Data in Line Protocol format>'

All data must be binary encoded and follow the line protocol format. All examples on this page include the --data-binary parameter in the curl commands. If an encoding mode other than --data-binary is used, an error may occur. The -d, --data-urlencode, and --data-ascii modes may remove the line feeds or introduce unexpected formats.

Options:

  • You can write points separated by line feeds to a database in one request.

  • Write points from a file. Use the at sign (@) to reference the file. Points in the file must be organized in line protocol format. Separate all the points with line feeds (\n). If the file contains carriage returns, the request will fail to be parsed.

We recommend that you write data in batches of 5,000 or 10,000 points. If you include a smaller number of points in each batch, a larger number of HTTP requests must be sent. This compromises the performance.

Examples

Write a point that uses a nanosecond timestamp to the mydb database

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:02:57 GMT

Write a point that uses the nanosecond timestamp of the local server to the mydb database

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:03:44 GMT

Write multiple points separated with line feeds to the mydb database

$ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
mymeas,mytag=2 myfield=34 1463689152000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:04:02 GMT

Write multiple points from the data.txt file to the mydb database

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

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:08:11 GMT

The following is a sample of the data in the data.txt file:

mymeas,mytag1=1 value=21 1463689680000000000
mymeas,mytag1=1 value=34 1463689690000000000
mymeas,mytag2=8 value=78 1463689700000000000
mymeas,mytag3=9 value=89 1463689710000000000

Status codes and responses

In general, 2xx status codes indicate success, 4xx status codes indicate that TSDB for InfluxDB® fails to parse the requests, and 5xx status codes indicate that the system is overloaded or significantly impaired. Errors are returned in JSON format.

Summary

HTTP status code

Description

204 No Content

The request is successful.

400 Bad Request

The request cannot be processed. This may be caused by invalid write protocol syntax or data writes to a field that previously accepted a different value type. For more information, see the JSON output.

401 Unauthorized

The request cannot be processed. This may be caused by invalid credentials for authentication.

404 Not Found

The request cannot be processed. This may be caused by an attempt to write data to a database that does not exist. For more information, see the JSON output.

500 Internal Server Error

The system is overloaded or significantly impaired. This may be caused by an attempt to write data to an RP that does not exist. For more information, see the JSON output.

Examples

Write data successfully

HTTP/1.1 204 No Content

Write a point that uses an incorrect timestamp

HTTP/1.1 400 Bad Request
[...]
{"error":"unable to parse 'mymeas,mytag=1 myfield=91 abc123': bad timestamp"}

Write an integer to a field that previously accepted floats

HTTP/1.1 400 Bad Request
[...]
{"error":"field type conflict: input field \"myfield\" on measurement \"mymeas\" is type int64, already exists as type float"}

Write data by using invalid credentials for authentication

HTTP/1.1 401 Unauthorized
[...]
{"error":"authorization failed"}

Write a point to a database that does not exist

HTTP/1.1 404 Not Found
[...]
{"error":"database not found: \"mydb1\""}

Write a point to an RP that does not exist

HTTP/1.1 500 Internal Server Error
[...]
{"error":"retention policy not found: myrp"}

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