---
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: 15204
product: InfluxDB Cloud (TSM)
version: cloud
---

[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:

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

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

```json
  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` required string

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

200 Success. 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` required string

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` required string

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.

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

`code` required string

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.

default Non 2XX error response from server.

`code` required string

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:
    
    ```json
    { "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:

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

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

```json
  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` required string

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

200 Success. 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

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

`code` required string

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.

default Internal server error

`code` required string

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:
    
    ```js
    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:
    
    ```js
    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:
    
    ```json
    { "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` required string

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

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

`ast` string

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

`code` required string

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.

default Internal server error.

`code` required string

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

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

`funcs` object\[\]

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

default Internal server error.

`code` required string

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` required string

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

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

`name` string

`params` object

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

`code` required string

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/)