openapi: 3.0.0
info:
title: Complete InfluxDB Cloud Authorizations (API tokens) Authorizations (API tokens) Query API
description: 'Create and manage authorizations (API tokens).
An _authorization_ contains a list of `read` and `write`
permissions for organization resources and provides an API token for authentication.
An authorization belongs to an organization and only contains permissions for that organization.
We recommend the following for managing your tokens:
- Create a generic user to create and manage tokens for writing data.
- Store your tokens in a secure password vault for future access.
### User sessions with authorizations
Optionally, when creating an authorization, you can scope it to a specific user.
If the user signs in with username and password, creating a _user session_,
the session carries the permissions granted by all the user''s authorizations.
For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/).
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
### Related endpoints
- [Signin](#tag/Signin)
- [Signout](#tag/Signout)
### Related guides
- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication)
- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/)
'
servers:
- url: ''
security:
- TokenAuthentication: []
tags:
- description: 'Retrieve data, analyze queries, and get query suggestions.
'
name: Query
paths:
/api/v2/query:
post:
description: '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](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).
#### Related guides
- [Query with the InfluxDB API](https://docs.influxdata.com/influxdb/cloud/query-data/execute-queries/influx-api/)
- [Get started with Flux](https://docs.influxdata.com/flux/v0.x/get-started/)
'
operationId: PostQuery
parameters:
- $ref: '#/components/parameters/TraceSpan'
- description: The content encoding (usually a compression algorithm) that the client can understand.
in: header
name: Accept-Encoding
schema:
default: identity
description: The content coding. Use `gzip` for compressed data or `identity` for unmodified, uncompressed data.
enum:
- gzip
- identity
type: string
- in: header
name: Content-Type
schema:
enum:
- application/json
- application/vnd.flux
type: string
- description: '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
- Requires either the `org` parameter or `orgID` parameter.
- Queries the bucket in the specified organization.
'
in: query
name: org
schema:
type: string
- description: '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
- Requires either the `org` parameter or `orgID` parameter.
- Queries the bucket in the specified organization.
'
in: query
name: orgID
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
application/vnd.flux:
example: "from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")\n"
schema:
type: string
description: Flux query or specification to execute
responses:
'200':
content:
application/csv:
example: 'result,table,_start,_stop,_time,region,host,_value
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62
'
schema:
type: string
description: Success. The response body contains query results.
headers:
Content-Encoding:
description: Lists encodings (usually compression algorithms) that have been applied to the response payload.
schema:
default: identity
description: 'The content coding: `gzip` for compressed data or `identity` for unmodified, uncompressed data.
'
enum:
- gzip
- identity
type: string
Trace-Id:
description: The trace ID, if generated, of the request.
schema:
description: Trace ID of a request.
type: string
'400':
content:
application/json:
examples:
orgNotFound:
summary: Organization not found
value:
code: invalid
message: 'failed to decode request body: organization not found'
schema:
$ref: '#/components/schemas/Error'
description: 'Bad request.
The response body contains detail about the error.
#### InfluxDB OSS
- Returns this error if the `org` parameter or `orgID` parameter doesn''t match an organization.
'
'401':
$ref: '#/components/responses/AuthorizationError'
'404':
$ref: '#/components/responses/ResourceNotFoundError'
'429':
description: "#### InfluxDB Cloud:\n - returns this error if a **read** or **write** request exceeds your\n plan's [adjustable service quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#adjustable-service-quotas)\n or if a **delete** request exceeds the maximum\n [global limit](https://docs.influxdata.com/influxdb/cloud/account-management/limits/#global-limits)\n - returns `Retry-After` header that describes when to try the write again.\n\n#### InfluxDB OSS:\n - doesn't return this error.\n"
headers:
Retry-After:
description: Non-negative decimal integer indicating seconds to wait before retrying the request.
schema:
format: int32
type: integer
'500':
$ref: '#/components/responses/InternalServerError'
default:
$ref: '#/components/responses/GeneralServerError'
summary: Query data
tags:
- Query
x-codeSamples:
- label: cURL
lang: Shell
source: "curl --request POST 'INFLUX_URL/api/v2/query?org=INFLUX_ORG' \\\n--header 'Content-Type: application/vnd.flux' \\\n--header 'Accept: application/csv \\\n--header 'Authorization: Token INFLUX_API_TOKEN' \\\n--data 'from(bucket: \"example-bucket\")\n |> range(start: -5m)\n |> filter(fn: (r) => r._measurement == \"example-measurement\")'\n"
/api/v2/query/analyze:
post:
description: "Analyzes a [Flux query](https://docs.influxdata.com/flux/v0.x/) for syntax\nerrors and returns the list of errors.\n\nIn the following sample query, `from()` is missing the property key.\n\n ```json\n { \"query\": \"from(: \\\"iot_center\\\")\\\n |> range(start: -90d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\",\n \"type\": \"flux\"\n }\n ```\n\nIf you pass this in a request to the `/api/v2/analyze` endpoint,\nInfluxDB returns an `errors` list that contains an error object for the missing key.\n\n#### Limitations\n\n- The endpoint doesn't validate values in the query--for example:\n\n - The following sample query has correct syntax, but contains an incorrect `from()` property key:\n\n ```json\n { \"query\": \"from(foo: \\\"iot_center\\\")\\\n |> range(start: -90d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\",\n \"type\": \"flux\"\n }\n ```\n\n If you pass this in a request to the `/api/v2/analyze` endpoint,\n InfluxDB returns an empty `errors` list.\n"
operationId: PostQueryAnalyze
parameters:
- $ref: '#/components/parameters/TraceSpan'
- in: header
name: Content-Type
schema:
enum:
- application/json
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Query'
description: Flux query to analyze
responses:
'200':
content:
application/json:
examples:
missingQueryPropertyKey:
description: "Returns an error object if the Flux query is missing a property key.\n\nThe following sample query is missing the _`bucket`_ property key:\n\n```json\n{\n \"query\": \"from(: \\\"iot_center\\\")\\\n ...\n}\n```\n"
summary: Missing property key error
value:
errors:
- character: 0
column: 6
line: 1
message: missing property key
schema:
$ref: '#/components/schemas/AnalyzeQueryResponse'
description: 'Success.
The response body contains the list of `errors`.
If the query syntax is valid, the endpoint returns an empty `errors` list.
'
'400':
content:
application/json:
examples:
invalidJSONStringValue:
description: If the request body contains invalid JSON, returns `invalid` and problem detail.
summary: Invalid JSON
value:
code: invalid
message: 'invalid json: invalid character ''\'''' looking for beginning of value'
schema:
$ref: '#/components/schemas/Error'
description: 'Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the problem.
'
headers:
X-Platform-Error-Code:
description: 'The reason for the error.
'
schema:
example: invalid
type: string
default:
content:
application/json:
examples:
emptyJSONObject:
description: 'If the request body contains an empty JSON object, returns `internal error`.
'
summary: Empty JSON object in request body
value:
code: internal error
message: An internal error has occurred - check server logs
schema:
$ref: '#/components/schemas/Error'
description: Internal server error
headers:
X-Influx-Error:
description: A string that describes the problem.
schema:
type: string
X-Influx-Reference:
description: The numeric reference code for the error type.
schema:
type: integer
X-Platform-Error-Code:
description: The reason for the error.
schema:
example: internal error
type: string
summary: Analyze a Flux query
tags:
- Query
x-codeSamples:
- label: 'cURL: Analyze a Flux query'
lang: Shell
source: "curl -v --request POST \\\n \"http://localhost:8086/api/v2/query/analyze\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --header 'Content-type: application/json' \\\n --header 'Accept: application/json' \\\n --data-binary @- << EOF\n { \"query\": \"from(bucket: \\\"iot_center\\\")\\\n |> range(start: -90d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\",\n \"type\": \"flux\"\n }\nEOF\n"
/api/v2/query/ast:
post:
description: "Analyzes a Flux query and returns a complete package source [Abstract Syntax\nTree (AST)](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#abstract-syntax-tree-ast)\nfor the query.\n\nUse this endpoint for deep query analysis such as debugging unexpected query\nresults.\n\nA Flux query AST provides a semantic, tree-like representation with contextual\ninformation about the query. The AST illustrates how the query is distributed\ninto different components for execution.\n\n#### Limitations\n\n- The endpoint doesn't validate values in the query--for example:\n\n The following sample Flux query has correct syntax, but contains an incorrect `from()` property key:\n\n ```js\n from(foo: \"iot_center\")\n |> range(start: -90d)\n |> filter(fn: (r) => r._measurement == \"environment\")\n ```\n\n The following sample JSON shows how to pass the query in the request body:\n\n ```js\n from(foo: \"iot_center\")\n |> range(start: -90d)\n |> filter(fn: (r) => r._measurement == \"environment\")\n ```\n\n The following code sample shows how to pass the query as JSON in the request body:\n\n ```json\n { \"query\": \"from(foo: \\\"iot_center\\\")\\\n |> range(start: -90d)\\\n |> filter(fn: (r) => r._measurement == \\\"environment\\\")\"\n }\n ```\n\n Passing this to `/api/v2/query/ast` will return a successful response\n with a generated AST.\n"
operationId: PostQueryAst
parameters:
- $ref: '#/components/parameters/TraceSpan'
- in: header
name: Content-Type
schema:
enum:
- application/json
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LanguageRequest'
description: The Flux query to analyze.
responses:
'200':
content:
application/json:
examples:
successResponse:
value:
ast:
files:
- body:
- expression:
argument:
argument:
arguments:
- location:
end:
column: 25
line: 1
source: 'bucket: "example-bucket"'
start:
column: 6
line: 1
properties:
- key:
location:
end:
column: 12
line: 1
source: bucket
start:
column: 6
line: 1
name: bucket
type: Identifier
location:
end:
column: 25
line: 1
source: 'bucket: "example-bucket"'
start:
column: 6
line: 1
type: Property
value:
location:
end:
column: 25
line: 1
source: '"example-bucket"'
start:
column: 14
line: 1
type: StringLiteral
value: example-bucket
type: ObjectExpression
callee:
location:
end:
column: 5
line: 1
source: from
start:
column: 1
line: 1
name: from
type: Identifier
location:
end:
column: 26
line: 1
source: 'from(bucket: "example-bucket")'
start:
column: 1
line: 1
type: CallExpression
call:
arguments:
- location:
end:
column: 46
line: 1
source: 'start: -5m'
start:
column: 36
line: 1
properties:
- key:
location:
end:
column: 41
line: 1
source: start
start:
column: 36
line: 1
name: start
type: Identifier
location:
end:
column: 46
line: 1
source: 'start: -5m'
start:
column: 36
line: 1
type: Property
value:
argument:
location:
end:
column: 46
line: 1
source: 5m
start:
column: 44
line: 1
type: DurationLiteral
values:
- magnitude: 5
unit: m
location:
end:
column: 46
line: 1
source: -5m
start:
column: 43
line: 1
operator: '-'
type: UnaryExpression
type: ObjectExpression
callee:
location:
end:
column: 35
line: 1
source: range
start:
column: 30
line: 1
name: range
type: Identifier
location:
end:
column: 47
line: 1
source: 'range(start: -5m)'
start:
column: 30
line: 1
type: CallExpression
location:
end:
column: 47
line: 1
source: 'from(bucket: "example-bucket") |> range(start: -5m)'
start:
column: 1
line: 1
type: PipeExpression
call:
arguments:
- location:
end:
column: 108
line: 1
source: 'fn: (r) => r._measurement == "example-measurement"'
start:
column: 58
line: 1
properties:
- key:
location:
end:
column: 60
line: 1
source: fn
start:
column: 58
line: 1
name: fn
type: Identifier
location:
end:
column: 108
line: 1
source: 'fn: (r) => r._measurement == "example-measurement"'
start:
column: 58
line: 1
type: Property
value:
body:
left:
location:
end:
column: 83
line: 1
source: r._measurement
start:
column: 69
line: 1
object:
location:
end:
column: 70
line: 1
source: r
start:
column: 69
line: 1
name: r
type: Identifier
property:
location:
end:
column: 83
line: 1
source: _measurement
start:
column: 71
line: 1
name: _measurement
type: Identifier
type: MemberExpression
location:
end:
column: 108
line: 1
source: r._measurement == "example-measurement"
start:
column: 69
line: 1
operator: ==
right:
location:
end:
column: 108
line: 1
source: '"example-measurement"'
start:
column: 87
line: 1
type: StringLiteral
value: example-measurement
type: BinaryExpression
location:
end:
column: 108
line: 1
source: (r) => r._measurement == "example-measurement"
start:
column: 62
line: 1
params:
- key:
location:
end:
column: 64
line: 1
source: r
start:
column: 63
line: 1
name: r
type: Identifier
location:
end:
column: 64
line: 1
source: r
start:
column: 63
line: 1
type: Property
value: null
type: FunctionExpression
type: ObjectExpression
callee:
location:
end:
column: 57
line: 1
source: filter
start:
column: 51
line: 1
name: filter
type: Identifier
location:
end:
column: 109
line: 1
source: 'filter(fn: (r) => r._measurement == "example-measurement")'
start:
column: 51
line: 1
type: CallExpression
location:
end:
column: 109
line: 1
source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")'
start:
column: 1
line: 1
type: PipeExpression
location:
end:
column: 109
line: 1
source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")'
start:
column: 1
line: 1
type: ExpressionStatement
imports: null
location:
end:
column: 109
line: 1
source: 'from(bucket: "example-bucket") |> range(start: -5m) |> filter(fn: (r) => r._measurement == "example-measurement")'
start:
column: 1
line: 1
metadata: parser-type=rust
package: null
type: File
package: main
type: Package
schema:
$ref: '#/components/schemas/ASTResponse'
description: 'Success.
The response body contains an Abstract Syntax Tree (AST) of the Flux query.
'
'400':
content:
application/json:
examples:
invalidASTValue:
description: 'If the request body contains a missing property key in `from()`,
returns `invalid` and problem detail.
'
summary: Invalid AST
value:
code: invalid
message: 'invalid AST: loc 1:6-1:19: missing property key'
schema:
$ref: '#/components/schemas/Error'
description: 'Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the problem.
'
headers:
X-Platform-Error-Code:
description: 'The reason for the error.
'
schema:
example: invalid
type: string
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Internal server error.
summary: Generate a query Abstract Syntax Tree (AST)
tags:
- Query
x-codeSamples:
- label: 'cURL: Analyze and generate AST for the query'
lang: Shell
source: "c
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/influxdb/refs/heads/main/openapi/influxdb-query-api-openapi.yml