Use the InfluxDB API endpoints to run queries, write data, check server status, and troubleshoot by tracking HTTP client requests, collecting server statistics, and using Go "pprof" profiles.
that is fully compatible with the **latest** client libraries.
If you are just getting started with InfluxDB 1.x today, we recommend adopting
the [latest client libraries](/influxdb/v1.8/tools/api_client_libraries/).
They allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source,
(when you are ready).
The following forward compatible APIs are available:
| Endpoint | Description |
|:---------- |:---------- |
| [/api/v2/query](#api-v2-query-http-endpoint) | Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and [Flux](/flux/latest/) |
| [/api/v2/write](#api-v2-write-http-endpoint) | Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API _(compatible with InfluxDB 2.0 client libraries)_ |
| [/health](#health-http-endpoint) | Check the health of your InfluxDB instance |
### `/api/v2/query/` HTTP endpoint
The `/api/v2/query` endpoint accepts `POST` HTTP requests.
| [/ping](#ping-http-endpoint) | Check the status of your InfluxDB instance and your version of InfluxDB |
| [/query](#query-http-endpoint) | Query data using **InfluxQL**, manage databases, retention policies, and users |
| [/write](#write-http-endpoint) | Write data to a database |
### `/debug/pprof` HTTP endpoint
InfluxDB supports the Go [`net/http/pprof`](https://golang.org/pkg/net/http/pprof/) HTTP endpoints, which are useful for troubleshooting. The `pprof` package serves runtime profiling data in the format expected by the _pprof_ visualization tool.
#### Definition
```
curl http://localhost:8086/debug/pprof/
```
The `/debug/pprof/` endpoint generates an HTML page with a list of built-in Go profiles and hyperlinks for each.
| Profile | Description
| :---------------- | :-------------------- |
| block | Stack traces that led to blocking on synchronization primitives. |
| goroutine | Stack traces of all current goroutines. |
| heap | Sampling of stack traces for heap allocations. |
| mutex | Stack traces of holders of contended mutexes. |
| threadcreate | Stack traces that led to the creation of new OS threads. |
To access one of the `/debug/pprof/` profiles listed above, use the following cURL request, substituting `<profile>` with the name of the profile. The resulting profile is output to a file specified in `<path/to/output-file>`.
| seconds=\<integer\> | Optional | Sets the duration (in seconds) over which the client collects information. The default duration is ten seconds. |
#### Examples
##### Track requests over a ten-second interval
```bash
$ curl http://localhost:8086/debug/requests
{
"user1:123.45.678.91": {"writes":1,"queries":0},
}
```
The response shows that, over the past ten seconds, the `user1` user sent one request to the `/write` endpoint and no requests to the `/query` endpoint from the `123.45.678.91` IP address.
The response shows that, over the past minute, `user1` sent three requests to the `/write` endpoint from `123.45.678.91`, `user1` sent 16 requests to the `/query` endpoint from `000.0.0.0`, and `user2` sent four requests to the `/write` endpoint from `xx.xx.xxx.xxx`.
### `/debug/vars` HTTP endpoint
InfluxDB exposes statistics and information about its runtime through the `/debug/vars` endpoint, which can be accessed using the following cURL command:
```bash
curl http://localhost:8086/debug/vars
```
Server statistics and information are displayed in JSON format.
For information about InfluxDB HTTP server metrics, see the [`httpd` measurement](/platform/monitoring/influxdata-platform/tools/measurements-internal/#httpd).
>**Note:** The [InfluxDB input plugin](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb) is available to collect metrics (using the `/debug/vars` endpoint) from specified Kapacitor instances. For a list of the measurements and fields, see the [InfluxDB input plugin README](https://github.com/influxdata/telegraf/tree/master/plugins/inputs/influxdb#readme).
### `/ping` HTTP endpoint
The ping endpoint accepts both `GET` and `HEAD` HTTP requests.
Use this endpoint to check the status of your InfluxDB instance and your version
of InfluxDB.
#### Definition
```
GET http://localhost:8086/ping
```
```
HEAD http://localhost:8086/ping
```
#### `verbose` option
By default, the `/ping` HTTP endpoint returns a simple HTTP 204 status response to let the client know that the server is running. Default value is `false`.
When `verbose` option is set to `true` (`/ping?verbose=true`), an HTTP 200 status is returned.
The `verbose=true` option is required for [Google Cloud Load Balancing](https://cloud.google.com/load-balancing/docs/health-check-concepts) health checks.
#### Example
You can use the `/ping` endpoint to find the build and version of an InfluxDB instance.
The `X-Influxdb-Build` header field displays the InfluxDB build type, either `OSS` (open source) or `ENT` (Enterprise).
The `X-Influxdb-Version` header field displays the InfluxDB version.
| 204 | Success! Your InfluxDB instance is up and running. |
### `/query` HTTP endpoint
The `/query` endpoint accepts `GET` and `POST` HTTP requests.
Use this endpoint to query data and manage databases, retention policies,
and users.
#### Definition
```
GET http://localhost:8086/query
```
```
POST http://localhost:8086/query
```
#### Verb usage
| Verb | Query Type |
| :---- | :--------- |
| GET | Use for all queries that start with: <br><br> [`SELECT`](/influxdb/v1.8/query_language/spec/#select)* <br><br> [`SHOW`](/influxdb/v1.8/query_language/spec/#show-continuous-queries) |
| POST | Use for all queries that start with: <br><br> [`ALTER`](/influxdb/v1.8/query_language/spec/#alter-retention-policy) <br><br> [`CREATE`](/influxdb/v1.8/query_language/spec/#create-continuous-query) <br><br> [`DELETE`](/influxdb/v1.8/query_language/spec/#delete) <br><br> [`DROP`](/influxdb/v1.8/query_language/spec/#drop-continuous-query) <br><br> [`GRANT`](/influxdb/v1.8/query_language/spec/#grant) <br><br> [`KILL`](/influxdb/v1.8/query_language/spec/#kill-query) <br><br> [`REVOKE`](/influxdb/v1.8/query_language/spec/#revoke) |
The `mymeas` [measurement](/influxdb/v1.8/concepts/glossary/#measurement) has two points.
The first point has the [timestamp](/influxdb/v1.8/concepts/glossary/#timestamp) `2017-03-01T00:16:18Z`, a `myfield` value of `33.1`, and no tag values for the `mytag1` and `mytag2` [tag keys](/influxdb/v1.8/concepts/glossary/#tag-key).
The second point has the timestamp `2017-03-01T00:17:18Z`, a `myfield` value of `12.4`, a `mytag1` value of `12`, and a `mytag2` value of `14`.
The same query in the InfluxDB [Command Line Interface](/influxdb/v1.8/tools/shell/) (CLI) returns the following table:
```sql
name: mymeas
time myfield mytag1 mytag2
---- ------- ------ ------
2017-03-01T00:16:18Z 33.1
2017-03-01T00:17:18Z 12.4 12 14
```
##### Query data with a `SELECT` statement and an `INTO` clause
```bash
$ curl -XPOST 'http://localhost:8086/query?db=mydb' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'
The response shows that InfluxDB writes two points to the `newmeas` [measurement](/influxdb/v1.8/concepts/glossary/#measurement).
Note that the system uses epoch 0 (`1970-01-01T00:00:00Z`) as a [null timestamp equivalent](/influxdb/v1.8/troubleshooting/frequently-asked-questions/#why-does-my-query-return-epoch-0-as-the-timestamp).
| 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 points, whichever occurs first. If set to a specific value, InfluxDB chunks responses by series or by that number of points.* |
| db=\<database_name> | Required for database-dependent queries (most [`SELECT`](/influxdb/v1.8/query_language/spec/#select) queries and [`SHOW`](/influxdb/v1.8/query_language/spec/#show-continuous-queries) queries require this parameter). | Sets the target [database](/influxdb/v1.8/concepts/glossary/#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` and `µ` indicate microseconds. |
| p=\<password> | Optional if you haven't [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-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. |
| q=\<query> | Required | InfluxQL string to execute. See also [Request Body](/influxdb/v1.8/tools/api/#request-body). |
| u=\<username> | Optional if you haven't [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-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`. |
\* InfluxDB does not truncate the number of rows returned for requests without the `chunked` parameter.
That behavior is configurable; see the [`max-row-limit`](/influxdb/v1.8/administration/config/#max-row-limit-0) configuration option for more information.
\** The InfluxDB API also supports basic authentication.
Use basic authentication if you've [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-authentication)
and aren't using the query string parameters `u` and `p`.
See below for an [example](#create-a-database-using-basic-authentication) of basic authentication.
#### Examples
##### Query data with a `SELECT` statement and return pretty-printed JSON
```bash
$ curl -G 'http://localhost:8086/query?db=mydb&pretty=true' --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"
]
]
}
]
}
]
}
```
##### Query data with a `SELECT` statement and return second precision epoch timestamps
```bash
$ curl -G 'http://localhost:8086/query?db=mydb&epoch=s' --data-urlencode 'q=SELECT * FROM "mymeas"'
The first point has no [tag values](/influxdb/v1.8/concepts/glossary/#tag-value) for the `mytag1` and `mytag2` [tag keys](/influxdb/v1.8/concepts/glossary/#tag-key).
| consistency=[any,one,quorum,all] | Optional, available with [InfluxDB Enterprise clusters](/enterprise_influxdb/v1.6/) only. | Sets the write consistency for the point. InfluxDB assumes that the write consistency is `one` if you do not specify `consistency`. See the [InfluxDB Enterprise documentation](/enterprise_influxdb/v1.6/concepts/clustering#write-consistency) for detailed descriptions of each consistency option. |
| db=\<database> | Required | Sets the target [database](/influxdb/v1.8/concepts/glossary/#database) for the write. |
| p=\<password> | Optional if you haven't [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-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=[n,u,ms,s,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=\<retention_policy_name> | Optional | Sets the target [retention policy](/influxdb/v1.8/concepts/glossary/#retention-policy-rp) for the write. InfluxDB writes to the `DEFAULT` retention policy if you do not specify a retention policy. |
| u=\<username> | Optional if you haven't [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-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`. |
\* The InfluxDB API also supports basic authentication.
Use basic authentication if you've [enabled authentication](/influxdb/v1.8/administration/authentication_and_authorization/#set-up-authentication)
and aren't using the query string parameters `u` and `p`.
See below for an [example](#write-a-point-to-the-database-mydb-using-basic-authentication) of basic authentication.
\*\* We recommend using the least precise precision possible as this can result
in significant improvements in compression.
#### Examples
##### Write a point to the database `mydb` with a timestamp in seconds
In general, status codes of the form `2xx` indicate success, `4xx` indicate
that InfluxDB could not understand the request, and `5xx` indicate that the
system is overloaded or significantly impaired.
Errors are returned in JSON.
##### Summary table
| HTTP status code | Description |
| :--------------- | :------------- |
| 204 No Content | Success! |
| 400 Bad Request | Unacceptable request. Can occur with an InfluxDB line protocol syntax error or if a user attempts to write values to a field that previously accepted a different value type. The returned JSON offers further information. |
| 401 Unauthorized | Unacceptable request. Can occur with invalid authentication credentials. |
| 404 Not Found | Unacceptable request. Can occur if a user attempts to write to a database that does not exist. The returned JSON offers further information. |
| 413 Request Entity Too Large | Unaccetable request. It will occur if the payload of the POST request is bigger than the maximum size allowed. See [`max-body-size`](/influxdb/v1.8/administration/config/#max-body-size-25000000) parameter for more details.
| 500 Internal Server Error | The system is overloaded or significantly impaired. Can occur if a user attempts to write to a retention policy that does not exist. The returned JSON offers further information. |
#### Examples
##### A successful write
```
HTTP/1.1 204 No Content
```
##### Write a point with 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 a float
```
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 a point with invalid authentication credentials
```
HTTP/1.1 401 Unauthorized
[...]
{"error":"authorization failed"}
```
##### Write a point to a database that doesn't exist
```
HTTP/1.1 404 Not Found
[...]
{"error":"database not found: \"mydb1\""}
```
##### Send a request body that is too large
```
HTTP/2 413 Request Entity Too Large
[...]
{"error":"Request Entity Too Large"}
```
##### Write a point to a retention policy that doesn't exist
