---
title: Query data
description: Retrieve data, analyze queries, and get query suggestions using the InfluxDB Cloud query API.
url: https://docs.influxdata.com/influxdb/cloud/api/query-data/
estimated_tokens: 4520
product: InfluxDB Cloud (TSM)
version: cloud
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/cloud/api/query-data/
---

[Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml)

Retrieve data, analyze queries, and get query suggestions using the InfluxDB Cloud query API.

POST`/api/v2/query`

### Query data

Retrieves data from buckets.

Use this endpoint to send a Flux query request and retrieve data from a bucket.

#### Rate limits (with InfluxDB Cloud)

`read` rate limits apply.
For more information, see [limits and adjustable quotas](/influxdb/cloud/account-management/limits/).

#### Related guides

* [Query with the InfluxDB API](/influxdb/cloud/query-data/execute-queries/influx-api/)
* [Get started with Flux](/flux/v0.x/get-started/)

#### Parameters

##### Query parameters

`org`string

An organization name or ID.

#### InfluxDB Cloud

* Doesn’t use the `org` parameter or `orgID` parameter.
* Queries the bucket in the organization associated with the authorization (API token).

#### InfluxDB OSS v2

* Requires either the `org` parameter or `orgID` parameter.
* Queries the bucket in the specified organization.

`orgID`string

An organization ID.

#### InfluxDB Cloud

* Doesn’t use the `org` parameter or `orgID` parameter.
* Queries the bucket in the organization associated with the authorization (API token).

#### InfluxDB OSS v2

* Requires either the `org` parameter or `orgID` parameter.
* Queries the bucket in the specified organization.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

`Accept-Encoding`string

The content encoding (usually a compression algorithm) that the client can understand.

Allowed values:`gzip`, `identity`

Default:`identity`

`Content-Type`string

Allowed values:`application/json`, `application/vnd.flux`

#### Request body

Flux query or specification to execute

Content-Type:`application/json`

`dialect`string

`extern`string

`now`string \<date-time\>

Specifies the time that should be reported as `now` in the query.
Default is the server `now` time.

`params`object

Key-value pairs passed as parameters during query execution.

To use parameters in your query, pass a *`query`* with `params` references (in dot notation)–for example:

```
  query: "from(bucket: params.mybucket)\
              |> range(start: params.rangeStart) |> limit(n:1)"
```

and pass *`params`* with the key-value pairs–for example:

```
  params: {
    "mybucket": "environment",
    "rangeStart": "-30d"
  }
```

During query execution, InfluxDB passes *`params`* to your script and substitutes the values.

#### Limitations

* If you use *`params`*, you can’t use *`extern`*.

`query`requiredstring

The query script to execute.

`type`string

The type of query. Must be “flux”.

Allowed:`flux`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/query" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "dialect": {},
  "extern": {},
  "now": "NOW",
  "params": {},
  "query": "QUERY",
  "type": "flux"
}'
```

#### Responses

200Success. The response body contains query results.

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if the `org` parameter or `orgID` parameter doesn’t match an organization.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

* The `Authorization: Token` header is missing or malformed.
* The API token value is missing from the header.
* The token doesn’t have sufficient permissions to write to this organization and bucket.

`code`string

The HTTP status code description. Default is `unauthorized`.

Allowed:`unauthorized`

`message`string

A human-readable message that may contain detail about the error.

404

Not found.
A requested resource was not found.
The response body contains the requested resource type and the name value
(if you passed it)–for example:

* `"organization name \"my-org\" not found"`
* `"organization not found"`: indicates you passed an ID that did not match
  an organization.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

429

#### InfluxDB Cloud:

* returns this error if a **read** or **write** request exceeds your
  plan’s [adjustable service quotas](/influxdb/cloud/account-management/limits/#adjustable-service-quotas)or if a **delete** request exceeds the maximum[global limit](/influxdb/cloud/account-management/limits/#global-limits)
* returns `Retry-After` header that describes when to try the write again.

#### InfluxDB OSS v2:

* doesn’t return this error.

500Internal server error.
The server encountered an unexpected situation.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultNon 2XX error response from server.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

POST`/api/v2/query/analyze`

### Analyze a Flux query

Analyzes a [Flux query](/flux/v0.x/) for syntax
errors and returns the list of errors.

In the following sample query, `from()` is missing the property key.

```
```json
{ "query": "from(: \"iot_center\")\
            |> range(start: -90d)\
            |> filter(fn: (r) => r._measurement == \"environment\")",
  "type": "flux"
}
```

```

If you pass this in a request to the `/api/v2/analyze` endpoint,
InfluxDB returns an `errors` list that contains an error object for the missing key.

#### Limitations

* The endpoint doesn’t validate values in the query–for example:

* The following sample query has correct syntax, but contains an incorrect `from()` property key:

  ```
  { "query": "from(foo: \"iot_center\")\
              |> range(start: -90d)\
              |> filter(fn: (r) => r._measurement == \"environment\")",
    "type": "flux"
  }
  ```

  If you pass this in a request to the `/api/v2/analyze` endpoint,
  InfluxDB returns an empty `errors` list.

#### Parameters

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

`Content-Type`string

Allowed values:`application/json`

#### Request body

Flux query to analyze

Content-Type:`application/json`

`dialect`string

`extern`string

`now`string \<date-time\>

Specifies the time that should be reported as `now` in the query.
Default is the server `now` time.

`params`object

Key-value pairs passed as parameters during query execution.

To use parameters in your query, pass a *`query`* with `params` references (in dot notation)–for example:

```
  query: "from(bucket: params.mybucket)\
              |> range(start: params.rangeStart) |> limit(n:1)"
```

and pass *`params`* with the key-value pairs–for example:

```
  params: {
    "mybucket": "environment",
    "rangeStart": "-30d"
  }
```

During query execution, InfluxDB passes *`params`* to your script and substitutes the values.

#### Limitations

* If you use *`params`*, you can’t use *`extern`*.

`query`requiredstring

The query script to execute.

`type`string

The type of query. Must be “flux”.

Allowed:`flux`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/query/analyze" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "dialect": {},
  "extern": {},
  "now": "NOW",
  "params": {},
  "query": "QUERY",
  "type": "flux"
}'
```

#### Responses

200Success.
The response body contains the list of `errors`.
If the query syntax is valid, the endpoint returns an empty `errors` list.

`errors`object[]

`character`integer

`column`integer

`line`integer

`message`string

400Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the problem.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultInternal server error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

POST`/api/v2/query/ast`

### Generate a query Abstract Syntax Tree (AST)

Analyzes a Flux query and returns a complete package source [Abstract Syntax
Tree (AST)](/influxdb/cloud/reference/glossary/#abstract-syntax-tree-ast)for the query.

Use this endpoint for deep query analysis such as debugging unexpected query
results.

A Flux query AST provides a semantic, tree-like representation with contextual
information about the query. The AST illustrates how the query is distributed
into different components for execution.

#### Limitations

* The endpoint doesn’t validate values in the query–for example:

  The following sample Flux query has correct syntax, but contains an incorrect `from()` property key:

  ```
  from(foo: "iot_center")
      |> range(start: -90d)
      |> filter(fn: (r) => r._measurement == "environment")
  ```

  The following sample JSON shows how to pass the query in the request body:

  ```
  from(foo: "iot_center")
  |> range(start: -90d)
  |> filter(fn: (r) => r._measurement == "environment")
  ```

  The following code sample shows how to pass the query as JSON in the request body:

  ```
  { "query": "from(foo: \"iot_center\")\
                  |> range(start: -90d)\
                  |> filter(fn: (r) => r._measurement == \"environment\")"
  }
  ```

  Passing this to `/api/v2/query/ast` will return a successful response
  with a generated AST.

#### Parameters

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

`Content-Type`string

Allowed values:`application/json`

#### Request body

The Flux query to analyze.

Content-Type:`application/json`

`query`requiredstring

The Flux query script to be analyzed.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/query/ast" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "query": "QUERY"
}'
```

#### Responses

200Success.
The response body contains an Abstract Syntax Tree (AST) of the Flux query.

`ast`string

400Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the problem.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultInternal server error.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

GET`/api/v2/query/suggestions`

### List Flux query suggestions

Lists Flux query suggestions. Each suggestion contains a[Flux function](/flux/v0.x/stdlib/all-functions/)name and parameters.

Use this endpoint to retrieve a list of Flux query suggestions used in the
InfluxDB Flux Query Builder.

#### Limitations

* When writing a query, avoid using `_functionName()` helper functions
  exposed by this endpoint. Helper function names have an underscore (`_`)
  prefix and aren’t meant to be used directly in queries–for example:

  * To sort on a column and keep the top n records, use the`top(n, columns=["_value"], tables=<-)` function instead of the `_sortLimit`helper function. `top` uses `_sortLimit`.

#### Related Guides

* [List of all Flux functions](/flux/v0.x/stdlib/all-functions/)

#### Parameters

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/query/suggestions" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains a list of Flux query suggestions–function
names used in the Flux Query Builder autocomplete suggestions.

`funcs`object[]

301Moved Permanently.
InfluxData has moved the URL of the endpoint.
Use `/api/v2/query/suggestions` (without a trailing slash).

defaultInternal server error.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

GET`/api/v2/query/suggestions/{name}`

### Retrieve a query suggestion for a branching suggestion

Retrieves a query suggestion that contains the name and parameters of the
requested function.

Use this endpoint to pass a branching suggestion (a Flux function name) and
retrieve the parameters of the requested function.

#### Limitations

* Use `/api/v2/query/suggestions/{name}` (without a trailing slash).`/api/v2/query/suggestions/{name}/` (note the trailing slash) results in a
  HTTP `301 Moved Permanently` status.

* The function `name` must exist and must be spelled correctly.

#### Related Guides

* [List of all Flux functions](/flux/v0.x/stdlib/all-functions/)

#### Parameters

##### Path parameters

`name`requiredstring

A [Flux function](/flux/v0.x/stdlib/all-functions/) name.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/query/suggestions/{name}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains the function name and parameters.

`name`string

`params`object

500Internal server error.
The value passed for *`name`* may have been misspelled.

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

#### Related

* [Query data](/influxdb/cloud/query-data/)