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, | 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= | Required for database-dependent queries (most | 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. |
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 |
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= | Required | The Influx Query Language (InfluxQL) command to run. |
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 read permission on databases. This parameter must be used with |
* 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 |
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 ( |
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 |
** 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®.