InfluxDB OSS API Service (2.7.0)

License: MIT

The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the /api/v2/ endpoint.

This documentation is generated from the InfluxDB OpenAPI specification.

Quick start

See the API Quick Start to get up and running authenticating with tokens, writing to buckets, and querying data.

InfluxDB API client libraries are available for popular languages and ready to import into your application.

Authentication

Use one of the following schemes to authenticate to the InfluxDB API:

Token authentication
Basic authentication
Querystring authentication

BasicAuthentication

Basic authentication scheme

Use the HTTP Basic authentication scheme for InfluxDB /api/v2 API operations that support it:

Syntax

Authorization: Basic BASE64_ENCODED_CREDENTIALS

To construct the BASE64_ENCODED_CREDENTIALS, combine the username and the password with a colon (USERNAME:PASSWORD), and then encode the resulting string in base64. Many HTTP clients encode the credentials for you before sending the request.

Warning: Base64-encoding can easily be reversed to obtain the original username and password. It is used to keep the data intact and does not provide security. You should always use HTTPS when authenticating or sending a request with sensitive information.

Examples

In the examples, replace the following:

USERNAME: InfluxDB username
PASSWORD: InfluxDB API token
INFLUX_URL: your InfluxDB URL

Encode credentials with cURL

The following example shows how to use cURL to send an API request that uses Basic authentication. With the --user option, cURL encodes the credentials and passes them in the Authorization: Basic header.

curl --get "INFLUX_URL/api/v2/signin"
    --user "USERNAME":"PASSWORD"

Encode credentials with Flux

The Flux http.basicAuth() function returns a Base64-encoded basic authentication header using a specified username and password combination.

Encode credentials with JavaScript

The following example shows how to use the JavaScript btoa() function to create a Base64-encoded string:

btoa('USERNAME:PASSWORD')

The output is the following:

'VVNFUk5BTUU6UEFTU1dPUkQ='

Once you have the Base64-encoded credentials, you can pass them in the Authorization header--for example:

curl --get "INFLUX_URL/api/v2/signin"
    --header "Authorization: Basic VVNFUk5BTUU6UEFTU1dPUkQ="

To learn more about HTTP authentication, see Mozilla Developer Network (MDN) Web Docs, HTTP authentication._

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

TokenAuthentication

Use the Token authentication scheme to authenticate to the InfluxDB API.

In your API requests, send an Authorization header. For the header value, provide the word Token followed by a space and an InfluxDB API token. The word Token is case-sensitive.

Syntax

Authorization: Token INFLUX_API_TOKEN

Example

Use Token authentication with cURL

The following example shows how to use cURL to send an API request that uses Token authentication:

curl --request GET "INFLUX_URL/api/v2/buckets" \
    --header "Authorization: Token INFLUX_API_TOKEN"

Replace the following:

INFLUX_URL: your InfluxDB URL
INFLUX_API_TOKEN: your InfluxDB API token

/authorizations endpoints

Security Scheme Type	API Key
Header parameter name:	Authorization

Supported operations

The following table shows the most common operations that the InfluxDB /api/v2 API supports. Some resources may support other operations that perform functions more specific to those resources. For example, you can use the PATCH /api/v2/scripts endpoint to update properties of a script resource.

Operation
Write	Writes (`POST`) data to a bucket.
Run	Executes (`POST`) a query or script and returns the result.
List	Retrieves (`GET`) a list of zero or more resources.
Create	Creates (`POST`) a new resource and returns the resource.
Update	Modifies (`PUT`) an existing resource to reflect data in your request.
Delete	Removes (`DELETE`) a specific resource.

Headers

InfluxDB HTTP API endpoints use standard HTTP request and response headers. The following table shows common headers used by many InfluxDB API endpoints. Some endpoints may use other headers that perform functions more specific to those endpoints--for example, the POST /api/v2/write endpoint accepts the Content-Encoding header to indicate the compression applied to line protocol in the request body.

Header	Value type	Description
`Accept`	string	The content type that the client can understand.
`Authorization`	string	The authorization scheme and credential.
`Content-Length`	integer	The size of the entity-body, in bytes, sent to the database.
`Content-Type`	string	The format of the data in the request body.

Pagination

Some InfluxDB API list operations may support the following query parameters for paginating results:

Query parameter	Value type	Description
`limit`	integer	The maximum number of records to return (after other parameters are applied).
`offset`	integer	The number of records to skip (before `limit`, after other parameters are applied).
`after`	string (resource ID)	Only returns resources created after the specified resource.

Limitations

For specific endpoint parameters and examples, see the endpoint definition.

If you specify an offset parameter value greater than the total number of records, then InfluxDB returns an empty list in the response (given offset skips the specified number of records).

The following example passes offset=50 to skip the first 50 results, but the user only has 10 buckets:

curl --request GET "INFLUX_URL/api/v2/buckets?limit=1&offset=50" \
     --header "Authorization: Token INFLUX_API_TOKEN"

The response contains the following:

{
  "links": {
      "prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
      "self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
  },
  "buckets": []
}

Response codes

InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses. The response body may include additional details. For details about a specific operation's response, see Responses and Response Samples for that operation.

API operations may return the following HTTP status codes:

Code	Status	Description
`200`	Success
`204`	Success. No content	InfluxDB doesn't return data for the request.
`400`	Bad request	May indicate one of the following: Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the `rejected_points` measurement in your `_monitoring` bucket. `Authorization` header is missing or malformed or the API token doesn't have permission for the operation.
`401`	Unauthorized	May indicate one of the following: `Authorization: Token` header is missing or malformed API token value is missing from the header API token doesn't have permission. For more information about token types and permissions, see Manage API tokens
`404`	Not found	Requested resource was not found. `message` in the response body provides details about the requested resource.
`413`	Request entity too large	Request payload exceeds the size limit.
`422`	Unprocessable entity	Request data is invalid. `code` and `message` in the response body provide details about the problem.
`429`	Too many requests	API token is temporarily over the request quota. The `Retry-After` header describes when to try the request again.
`500`	Internal server error
`503`	Service unavailable	Server is temporarily unavailable to process the request. The `Retry-After` header describes when to try the request again.

Data I/O endpoints

Delete data

Deletes data from a bucket.

Use this endpoint to delete points from a bucket in a specified time range.

InfluxDB Cloud

Does the following when you send a delete request:
1. Validates the request and queues the delete.
2. If queued, responds with success (HTTP 2xx status code); error otherwise.
3. Handles the delete asynchronously and reaches eventual consistency.

To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

Validates the request, handles the delete synchronously, and then responds with success or failure.

Required permissions

write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Delete data
Learn how to use delete predicate syntax.
Learn how InfluxDB handles deleted tags and deleted fields.

Authorizations:

TokenAuthentication

query Parameters

bucket	string A bucket name or ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence.
bucketID	string A bucket ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence.
org	string An organization name or ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Deletes data from the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. Deletes data from the bucket in the specified organization. If you pass both `orgID` and `org`, they must both be valid.
orgID	string An organization ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Deletes data from the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. Deletes data from the bucket in the specified organization. If you pass both `orgID` and `org`, they must both be valid.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Time range parameters and an optional delete predicate expression.

To select points to delete within the specified time range, pass a delete predicate expression in the predicate property of the request body. If you don't pass a predicate, InfluxDB deletes all data with timestamps in the specified time range.

Delete data
Learn how to use delete predicate syntax.

predicate	string An expression in delete predicate syntax.
start required	string <date-time> A timestamp (RFC3339 date/time format). The earliest time to delete from.
stop required	string <date-time> A timestamp (RFC3339 date/time format). The latest time to delete from.

Responses

Request samples

Payload
cURL

Content type

application/json

{"predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")",
"start": "2019-08-24T14:15:22Z",
"stop": "2019-08-24T14:15:22Z"
}

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

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.

Authorizations:

TokenAuthentication

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 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 Requires either the `org` parameter or `orgID` parameter. Queries the bucket in the specified organization.

header Parameters

Accept-Encoding	string Default: identity Enum: "gzip" "identity" The content encoding (usually a compression algorithm) that the client can understand.
Content-Type	string Enum: "application/json" "application/vnd.flux"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema:
application/json
application/json
application/vnd.flux

Flux query or specification to execute

	object (Dialect) Options for tabular data output. Default output is annotated CSV with headers. For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.
	object (File) Represents a source from a single file
now	string <date-time> Specifies the time that should be reported as `now` in the query. Default is the server `now` time.
query required	string The query script to execute.
type	string Value: "flux" The type of query. Must be "flux".

Responses

Request samples

Payload
cURL

Content type

{"dialect": {"annotations": ["group"
],
"commentPrefix": "#",
"dateTimeFormat": "RFC3339",
"delimiter": ",",
"header": true
},
"extern": {"body": [{"text": "string",
"type": "string"
}
],
"imports": [{"as": {"name": "string",
"type": "string"
},
"path": {"type": "string",
"value": "string"
},
"type": "string"
}
],
"name": "string",
"package": {"name": {"name": "string",
"type": "string"
},
"type": "string"
},
"type": "string"
},
"now": "2019-08-24T14:15:22Z",
"query": "string",
"type": "flux"
}

Response samples

Content type

application/csv

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

List tasks

Retrieves a list of tasks.

To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default limit.

Process data with InfluxDB tasks

Authorizations:

TokenAuthentication

query Parameters

after	string A task ID. Only returns tasks created after the specified task.
limit	integer [ 1 .. 500 ] Default: 100 The maximum number of tasks to return. Default is `100`. The minimum is `1` and the maximum is `500`. To reduce the payload size, combine `type=basic` and `limit` (see Request samples). For more information about the `basic` response, see the `type` parameter.
name	string A task name. Only returns tasks with the specified name. Different tasks may have the same name.
org	string An organization name. Only returns tasks owned by the specified organization.
orgID	string An organization ID. Only returns tasks owned by the specified organization.
status	string Enum: "active" "inactive" A task status. Only returns tasks that have the specified status (`active` or `inactive`).
type	string Default: "" Enum: "basic" "system" A task type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).
user	string A user ID. Only returns tasks owned by the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: all tasks, basic output

curl https://localhost:8086/api/v2/tasks/?limit=-1&type=basic \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token INFLUX_API_TOKEN'

Response samples

200
401
500
default

Content type

application/json

Example

A sample response body for the ?type=basic parameter. type=basic omits some task fields (createdAt and updatedAt) and field values (org, flux) in the response.

{"links": {"self": "/api/v2/tasks?limit=100"
},
"tasks": [{"every": "30m",
"flux": "",
"id": "09956cbb6d378000",
"labels": [ ],
"lastRunStatus": "success",
"latestCompleted": "2022-06-30T15:00:00Z",
"links": {"labels": "/api/v2/tasks/09956cbb6d378000/labels",
"logs": "/api/v2/tasks/09956cbb6d378000/logs",
"members": "/api/v2/tasks/09956cbb6d378000/members",
"owners": "/api/v2/tasks/09956cbb6d378000/owners",
"runs": "/api/v2/tasks/09956cbb6d378000/runs",
"self": "/api/v2/tasks/09956cbb6d378000"
},
"name": "task1",
"org": "",
"orgID": "48c88459ee424a04",
"ownerID": "0772396d1f411000",
"status": "active"
}
]
}

Create a task

Creates a task and returns the task.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The task to create.

description	string An optional description of the task.
flux required	string The Flux script to run for this task.
org	string The name of the organization that owns this Task.
orgID	string The ID of the organization that owns this Task.
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Payload
cURL: create a task

Content type

application/json

{"description": "string",
"flux": "string",
"org": "string",
"orgID": "string",
"status": "active"
}

Response samples

201
400
401
500
default

Content type

application/json

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

Retrieve a task

Retrieves a task.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

Start a task run, overriding the schedule

Schedules a task run to start immediately, ignoring scheduled runs.

Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks.

To retry a previous run (and avoid creating a new run), use the POST /api/v2/tasks/{taskID}/runs/{runID}/retry endpoint.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

scheduledFor

string or null <date-time>

The time RFC3339 date/time format used for the run's now option. Default is the server now time.

Responses

Request samples

Payload

Content type

application/json

{"scheduledFor": "2019-08-24T14:15:22Z"
}

Response samples

201
401
500
default

Content type

application/json

{"finishedAt": "2006-01-02T15:04:05.999999999Z07:00",
"flux": "string",
"id": "string",
"links": {"retry": "/api/v2/tasks/1/runs/1/retry",
"self": "/api/v2/tasks/1/runs/1",
"task": "/api/v2/tasks/1"
},
"log": [{"message": "Halt and catch fire",
"runID": "string",
"time": "2006-01-02T15:04:05.999999999Z07:00"
}
],
"requestedAt": "2006-01-02T15:04:05.999999999Z07:00",
"scheduledFor": "2019-08-24T14:15:22Z",
"startedAt": "2006-01-02T15:04:05.999999999Z07:00",
"status": "scheduled",
"taskID": "string"
}

Write data

Writes data to a bucket.

Use this endpoint to send data in line protocol format to InfluxDB.

InfluxDB Cloud

Does the following when you send a write request:
1. Validates the request and queues the write.
2. If queued, responds with success (HTTP 2xx status code); error otherwise.
3. Handles the delete asynchronously and reaches eventual consistency.
To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

Validates the request and handles the write synchronously.
If all points were written successfully, responds with HTTP 2xx status code; otherwise, returns the first line that failed.

Required permissions

write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Authorizations:

TokenAuthentication

query Parameters

bucket required	string A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket.
org required	string An organization name or ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Writes data to the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. If you pass both `orgID` and `org`, they must both be valid. Writes data to the bucket in the specified organization.
orgID	string An organization ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Writes data to the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. If you pass both `orgID` and `org`, they must both be valid. Writes data to the bucket in the specified organization.
precision	string (WritePrecision) Enum: "ms" "s" "us" "ns" The precision for unix timestamps in the line protocol batch.

header Parameters

Accept	string Default: application/json Value: "application/json" The content type that the client can understand. Writes only return a response body if they fail--for example, due to a formatting problem or quota limit. InfluxDB Cloud Returns only `application/json` for format and limit errors. Returns only `text/html` for some quota limit errors. InfluxDB OSS Returns only `application/json` for format and limit errors. Related guides Troubleshoot issues writing data
Content-Encoding	string Default: identity Enum: "gzip" "identity" The compression applied to the line protocol in the request payload. To send a gzip payload, pass `Content-Encoding: gzip` header.
Content-Length	integer The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the `max body` configuration option, the server responds with status code `413`.
Content-Type	string Default: text/plain; charset=utf-8 Enum: "text/plain" "text/plain; charset=utf-8" The format of the data in the request body. To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`.
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

In the request body, provide data in line protocol format.

To send compressed data, do the following:

Use gzip to compress the line protocol data.
In your request, send the compressed data and the Content-Encoding: gzip header.

Best practices for optimizing writes

string <byte>

Responses

Request samples

Payload

Content type

text/plain

airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000

Response samples

Content type

application/json

Example

{"code": "invalid",
"message": "partial write error (2 written): unable to parse 'air_sensor,service=S1,sensor=L1 temperature=\"90.5\",humidity=70.0 1632850122': schema: field type for field \"temperature\" not permitted by schema; got String but expected Float"
}

Security and access endpoints

List authorizations

Lists authorizations.

To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations.

InfluxDB Cloud

InfluxDB Cloud doesn't expose API token values in GET /api/v2/authorizations responses; returns token: redacted for all authorizations.

Required permissions

To retrieve an authorization, the request must use an API token that has the following permissions:

read-authorizations
read-user for the user that the authorization is scoped to

View tokens

Authorizations:

TokenAuthentication

query Parameters

org	string An organization name. Only returns authorizations that belong to the specified organization.
orgID	string An organization ID. Only returns authorizations that belong to the specified organization.
token	string An API token value. Specifies an authorization by its `token` property value and returns the authorization. InfluxDB OSS Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. Limitations The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn't exist, then the response body contains an empty list.
user	string A user name. Only returns authorizations scoped to the specified user.
userID	string A user ID. Only returns authorizations scoped to the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
401
500
default

Content type

application/json

{"authorizations": [{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Create an authorization

Creates an authorization and returns the authorization with the generated API token.

Use this endpoint to create an authorization, which generates an API token with permissions to read or write to a specific resource or type of resource. The API token is the authorization's token property value.

To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens.

InfluxDB allows access to the API token value immediately after the authorization is created.
You can’t change access (read/write) permissions for an API token after it’s created.
Tokens stop working when the user who created the token is deleted.

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.

Required permissions

write-authorizations
write-user for the user that the authorization is scoped to

Create a token

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The authorization to create.

description	string A description of the token.
orgID required	string An organization ID. Specifies the organization that owns the authorization.
required	Array of objects (Permission) non-empty A list of permissions for an authorization. In the list, provide at least one `permission` object. In a `permission`, the `resource.type` property grants access to all resources of the specified type. To grant access to only a specific resource, specify the `resource.id` property.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.
userID	string A user ID. Specifies the user that the authorization is scoped to. When a user authenticates with username and password, InfluxDB generates a user session with all the permissions specified by all the user's authorizations.

Responses

Request samples

Payload

Content type

application/json

Example

Creates an authorization.

{"description": "iot_users read buckets",
"orgID": "INFLUX_ORG_ID",
"permissions": [{"action": "read",
"resource": {"type": "buckets"
}
}
]
}

Response samples

201
400
401
500
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Delete an authorization

Deletes an authorization.

Use the endpoint to delete an API token.

If you want to disable an API token instead of delete it, update the authorization's status to inactive.

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "id must have a length of 16 bytes"
}

Retrieve an authorization

Retrieves an authorization.

Use this endpoint to retrieve information about an API token, including the token's permissions and the user that the token is scoped to.

InfluxDB OSS

InfluxDB OSS returns API token values in authorizations.
If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.

View tokens

View tokens

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Update an API token to be active or inactive

Updates an authorization.

Use this endpoint to set an API token's status to be active or inactive. InfluxDB rejects requests that use inactive API tokens.

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

In the request body, provide the authorization properties to update.

description	string A description of the token.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"status": "active"
}

Response samples

200
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

List organizations

Lists organizations.

To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default limit.

InfluxDB Cloud

Only returns the organization that owns the token passed in the request.

View organizations

Authorizations:

TokenAuthentication

query Parameters

descending	boolean Default: false
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
org	string An organization name. Only returns the specified organization.
orgID	string An organization ID. Only returns the specified organization.
userID	string A user ID. Only returns organizations where the specified user is a member or owner.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/orgs"
},
"orgs": [{"createdAt": "2022-07-17T23:00:30.778487Z",
"description": "Example InfluxDB organization",
"id": "INFLUX_ORG_ID",
"links": {"buckets": "/api/v2/buckets?org=INFLUX_ORG",
"dashboards": "/api/v2/dashboards?org=INFLUX_ORG",
"labels": "/api/v2/orgs/INFLUX_ORG_ID/labels",
"logs": "/api/v2/orgs/INFLUX_ORG_ID/logs",
"members": "/api/v2/orgs/INFLUX_ORG_ID/members",
"owners": "/api/v2/orgs/INFLUX_ORG_ID/owners",
"secrets": "/api/v2/orgs/INFLUX_ORG_ID/secrets",
"self": "/api/v2/orgs/INFLUX_ORG_ID",
"tasks": "/api/v2/tasks?org=InfluxData"
},
"name": "INFLUX_ORG",
"updatedAt": "2022-07-17T23:00:30.778487Z"
}
]
}

Retrieve an organization

Retrieves an organization.

Use this endpoint to retrieve information for a specific organization.

View organizations

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
404
500
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"defaultStorageType": "tsm",
"description": "string",
"id": "string",
"links": {"buckets": "/api/v2/buckets?org=myorg",
"dashboards": "/api/v2/dashboards?org=myorg",
"labels": "/api/v2/orgs/1/labels",
"members": "/api/v2/orgs/1/members",
"owners": "/api/v2/orgs/1/owners",
"secrets": "/api/v2/orgs/1/secrets",
"self": "/api/v2/orgs/1",
"tasks": "/api/v2/tasks?org=myorg"
},
"name": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

List all members of an organization

Lists all users that belong to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Member permissions are separate from API token permissions.
Member permissions are used in the context of the InfluxDB UI.

Required permissions

read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve members for.

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to retrieve users for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/orgs/055aa4783aa38398/members"
},
"users": [{"id": "791df274afd48a83",
"links": {"self": "/api/v2/users/791df274afd48a83"
},
"name": "example_user_1",
"role": "member",
"status": "active"
},
{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_2",
"role": "owner",
"status": "active"
}
]
}

Remove a member from an organization

Removes a member from an organization.

Use this endpoint to remove a user's member privileges for an organization. Removing member privileges removes the user's read and write permissions from the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Member permissions are separate from API token permissions.
Member permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Manage members

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The ID of the organization to remove a user from.
userID required	string The ID of the user to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

List all owners of an organization

Lists all owners of an organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Required permissions

read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve a list of owners from.

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to list owners for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"links": {"self": "/api/v2/orgs/055aa4783aa38398/owners"
},
"users": [{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_2",
"role": "owner",
"status": "active"
}
]
}

Remove an owner from an organization

Removes an owner from the organization.

Organization owners have permission to delete organizations and remove user and member permissions from the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Owner permissions are separate from API token permissions.
Owner permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Authorizations

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The ID of the organization to remove an owner from.
userID required	string The ID of the user to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

List all secret keys for an organization

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"secrets": ["string"
],
"links": {"org": "string",
"self": "string"
}
}

Delete a secret from an organization

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The organization ID.
secretID required	string The secret ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Delete secrets from an organization Deprecated

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Secret key to delete

secrets

Array of strings

Responses

Request samples

Payload

Content type

application/json

{"secrets": ["string"
]
}

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Create a user session.

Authenticates Basic authentication credentials for a user, and then, if successful, generates a user session.

To authenticate a user, pass the HTTP Authorization header with the Basic scheme and the base64-encoded username and password. For syntax and more information, see Basic Authentication for syntax and more information.

If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the Set-Cookie response header.

InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance.

User sessions with authorizations

In InfluxDB Cloud, a user session inherits all the user's permissions for the organization.
In InfluxDB OSS, a user session inherits all the user's permissions for all the organizations that the user belongs to.

Signout

Authorizations:

BasicAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: signin with --user option encoding

curl --request POST http://localhost:8086/api/v2/signin \
     --user "USERNAME:PASSWORD"

Response samples

401
403
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Expire a user session

Expires a user session specified by a session cookie.

Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the POST /api/v2/signin endpoint.

For example, the POST /api/v2/signout endpoint represents the third step in the following three-step process to authenticate a user, retrieve the user resource, and then expire the session:

Send a request with the user's Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
Send a request to the GET /api/v2/me endpoint, passing the stored session cookie from step 1 to retrieve user information.
Send a request to the POST /api/v2/signout endpoint, passing the stored session cookie to expire the session.

See the complete example in request samples.

InfluxDB stores user sessions in memory only. If a user doesn't sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance.

To learn more about cookies in HTTP requests, see Mozilla Developer Network (MDN) Web Docs, HTTP cookies.

Signin

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: sign in a user, verify the user session, and then end the session

# The following example shows how to use cURL and the InfluxDB API
# to do the following:
# 1. Sign in a user with a username and password.
# 2. Check that the user session exists for the user.
# 3. Sign out the user to expire the session.
# 4. Check that the session is no longer active.

# 1. Send a request to `POST /api/v2/signin` to sign in the user.
#    In your request, pass the following:
#
#      - `--user` option with basic authentication credentials.
#      - `-c` option with a file path where cURL will write cookies.

      curl --request POST \
        -c ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/signin" \
        --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}"

# 2. To check that a user session exists for the user in step 1,
#    send a request to `GET /api/v2/me`.
#    In your request, pass the `-b` option with the session cookie file path from step 1.

      curl --request GET \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/me"

#    InfluxDB responds with the `user` resource.

# 3. Send a request to `POST /api/v2/signout` to expire the user session.
#    In your request, pass the `-b` option with the session cookie file path from step 1.

      curl --request POST \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/signout"

#     If the user session is successfully expired, InfluxDB responds with
      an HTTP `204` status code.

# 4. To check that the user session is expired, call `GET /api/v2/me` again,
#    passing the `-b` option with the cookie file path.

      curl --request GET \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/me"

#    If the user session is expired, InfluxDB responds with an HTTP `401` status code.

Response samples

401
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List users

Lists users. Default limit is 20.

To limit which users are returned, pass query parameters in your request.

Required permissions for InfluxDB OSS

Action	Permission required	Restriction
List all users	Operator token
List a specific user	`read-users` or `read-user USER_ID`

USER_ID is the ID of the user that you want to retrieve.

View users.

Authorizations:

TokenAuthentication

query Parameters

after	string A resource ID to seek from. Returns records created after the specified record; results don't include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see Pagination.
id	string A user ID. Only lists the specified user.
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
name	string A user name. Only lists the specified user.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
422
500
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}
]
}

Retrieve a user

Retrieves a user.

Manage users

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

A user ID. Retrieves the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}

Update a password

Updates a user password.

InfluxDB Cloud

Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

The ID of the user to set the password for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password

required

string

Responses

Request samples

Payload
cURL: use HTTP POST to update the user password

Content type

application/json

{"password": "string"
}

Response samples

400
default

Content type

application/json

{"code": "invalid",
"message": "passwords cannot be changed through the InfluxDB Cloud API"
}

Update a password

Updates a user password.

Use this endpoint to let a user authenticate with Basic authentication credentials and set a new password.

InfluxDB Cloud

Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Authorizations:

BasicAuthentication

path Parameters

userID

required

string

The ID of the user to set the password for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password

required

string

Responses

Request samples

Payload
cURL: use Basic auth to update the user password

Content type

application/json

{"password": "string"
}

Response samples

400
default

Content type

application/json

{"code": "invalid",
"message": "passwords cannot be changed through the InfluxDB Cloud API"
}

System information endpoints

List all top level routes

Retrieves all the top level routes for the InfluxDB API.

Limitations

Only returns top level routes--for example, the response contains "tasks":"/api/v2/tasks", and doesn't contain resource-specific routes for tasks (/api/v2/tasks/TASK_ID/...).

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200

Content type

application/json

{"authorizations": "http://example.com",
"buckets": "http://example.com",
"dashboards": "http://example.com",
"external": {"statusFeed": "http://example.com"
},
"flags": "http://example.com",
"me": "http://example.com",
"orgs": "http://example.com",
"query": {"analyze": "http://example.com",
"ast": "http://example.com",
"self": "http://example.com",
"suggestions": "http://example.com"
},
"setup": "http://example.com",
"signin": "http://example.com",
"signout": "http://example.com",
"sources": "http://example.com",
"system": {"debug": "http://example.com",
"health": "http://example.com",
"metrics": "http://example.com"
},
"tasks": "http://example.com",
"telegrafs": "http://example.com",
"users": "http://example.com",
"variables": "http://example.com",
"write": "http://example.com"
}

Retrieve runtime configuration

Returns the active runtime configuration of the InfluxDB instance.

In InfluxDB v2.2+, use this endpoint to view your active runtime configuration, including flags and environment variables.

View your runtime server configuration

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
default

Content type

application/json

{"config": { }
}

Retrieve all runtime profiles

Collects samples and returns reports for the following Go runtime profiles:

allocs: All past memory allocations
block: Stack traces that led to blocking on synchronization primitives
cpu: (Optional) Program counters sampled from the executing stack. Include by passing the cpu query parameter with a duration value. Equivalent to the report from GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS.
goroutine: All current goroutines
heap: Memory allocations for live objects
mutex: Holders of contended mutexes
threadcreate: Stack traces that led to the creation of new OS threads

Authorizations:

TokenAuthentication

query Parameters

cpu	string <duration> Collects and returns CPU profiling data for the specified duration. InfluxDB duration

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: Get all profiles
Shell: Get all profiles except CPU

# Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.

curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz

# x profiles/cpu.pb.gz
# x profiles/goroutine.pb.gz
# x profiles/block.pb.gz
# x profiles/mutex.pb.gz
# x profiles/heap.pb.gz
# x profiles/allocs.pb.gz
# x profiles/threadcreate.pb.gz

# Analyze a profile.

go tool pprof profiles/heap.pb.gz

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the memory allocations runtime profile

Returns a Go runtime profile report of all past memory allocations. allocs is the same as the heap profile, but changes the default pprof display to -alloc_space, the total number of bytes allocated since the program began (including garbage-collected bytes).

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/allocs

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

# At the prompt, get the top N memory allocations.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the block runtime profile

Collects samples and returns a Go runtime profile report of stack traces that led to blocking on synchronization primitives.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/block

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the command line invocation

Returns the command line that invoked InfluxDB.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the goroutines runtime profile

Collects statistics and returns a Go runtime profile report of all current goroutines.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as `human-readable text with comments that translate addresses to function names and line numbers for debugging.` `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/goroutine

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the heap runtime profile

Collects statistics and returns a Go runtime profile report of memory allocations for live objects.

To run garbage collection before sampling, pass the gc query parameter with a value of 1.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
gc	integer <int64> Enum: 0 1 `0`: (Default) don't force garbage collection before sampling. `1`: Force garbage collection before sampling.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/heap

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

# At the prompt, get the top N memory-intensive nodes.

(pprof) top10

# pprof displays the list:
#   Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total
#   Dropped 895 nodes (cum <= 0.83MB)
#   Showing top 10 nodes out of 143

Response samples

200
default

Content type

No sample

Retrieve the mutual exclusion (mutex) runtime profile

Collects statistics and returns a Go runtime profile report of lock contentions. The profile contains stack traces of holders of contended mutual exclusions (mutexes).

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/mutex

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the CPU runtime profile

Collects statistics and returns a Go runtime profile report of program counters on the executing stack.

Authorizations:

TokenAuthentication

query Parameters

seconds

string <int64>

Number of seconds to collect profile data. Default is 30 seconds.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Download the profile report.

curl http://localhost:8086/debug/pprof/profile -o cpu

# Analyze the profile in interactive mode.

go tool pprof ./cpu

# At the prompt, get the top N functions most often running
# or waiting during the sample period.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the threadcreate runtime profile

Collects statistics and returns a Go runtime profile report of stack traces that led to the creation of new OS threads.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/threadcreate

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

200
default

Content type

No sample

Retrieve the runtime execution trace

Collects profile data and returns trace execution events for the current program.

Authorizations:

TokenAuthentication

query Parameters

seconds

string <int64>

Number of seconds to collect profile data.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool trace

# Download the trace file.

curl http://localhost:8086/debug/pprof/trace -o trace

# Analyze the trace.

go tool trace ./trace

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the health of the instance

Returns the health of the instance.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
503
default

Content type

application/json

{"checks": [{ }
],
"commit": "string",
"message": "string",
"name": "string",
"status": "pass",
"version": "string"
}

Retrieve workload performance metrics

Returns metrics about the workload performance of an InfluxDB instance.

Use this endpoint to get performance, resource, and usage metrics.

For the list of metrics categories, see InfluxDB OSS metrics.
Learn how to use InfluxDB to scrape Prometheus metrics.
Learn how InfluxDB parses the Prometheus exposition format.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

text/plain

# HELP go_threads Number of OS threads created.
# TYPE go_threads gauge
go_threads 19
# HELP http_api_request_duration_seconds Time taken to respond to HTTP request
# TYPE http_api_request_duration_seconds histogram
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.005"} 4
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.01"} 4
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.025"} 5

Get the status of the instance

Retrieves the status and InfluxDB version of the instance.

Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP 204 status code to inform you the instance is available.

InfluxDB Cloud

Isn't versioned and doesn't return X-Influxdb-Version in the headers.

Influx ping

Authorizations:

TokenAuthentication

Responses

Request samples

cURL

curl --request GET "http://localhost:8086/ping"

Get the readiness of an instance at startup

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"started": "2019-03-13T10:09:33.891196-04:00",
"status": "ready",
"up": "14m45.911966424s"
}

List all known resources

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

["string"
]

Authorizations (API tokens)

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 creating a generic user to create and manage tokens for writing data.

User sessions with authorizations

Optionally, when creating an authorization, you can scope it to a specific user. If a 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. To create a user session, use the POST /api/v2/signin endpoint.

Signin
Signout

List authorizations

Lists authorizations.

To limit which authorizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all authorizations.

InfluxDB Cloud

InfluxDB Cloud doesn't expose API token values in GET /api/v2/authorizations responses; returns token: redacted for all authorizations.

Required permissions

To retrieve an authorization, the request must use an API token that has the following permissions:

read-authorizations
read-user for the user that the authorization is scoped to

View tokens

Authorizations:

TokenAuthentication

query Parameters

org	string An organization name. Only returns authorizations that belong to the specified organization.
orgID	string An organization ID. Only returns authorizations that belong to the specified organization.
token	string An API token value. Specifies an authorization by its `token` property value and returns the authorization. InfluxDB OSS Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter, applies other parameters, and then returns the result. Limitations The parameter is non-repeatable. If you specify more than one, only the first one is used. If a resource with the specified property value doesn't exist, then the response body contains an empty list.
user	string A user name. Only returns authorizations scoped to the specified user.
userID	string A user ID. Only returns authorizations scoped to the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
401
500
default

Content type

application/json

{"authorizations": [{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Create an authorization

Creates an authorization and returns the authorization with the generated API token.

Use this endpoint to create an authorization, which generates an API token with permissions to read or write to a specific resource or type of resource. The API token is the authorization's token property value.

To follow best practices for secure API token generation and retrieval, InfluxDB enforces access restrictions on API tokens.

InfluxDB allows access to the API token value immediately after the authorization is created.
You can’t change access (read/write) permissions for an API token after it’s created.
Tokens stop working when the user who created the token is deleted.

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.

Required permissions

write-authorizations
write-user for the user that the authorization is scoped to

Create a token

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The authorization to create.

description	string A description of the token.
orgID required	string An organization ID. Specifies the organization that owns the authorization.
required	Array of objects (Permission) non-empty A list of permissions for an authorization. In the list, provide at least one `permission` object. In a `permission`, the `resource.type` property grants access to all resources of the specified type. To grant access to only a specific resource, specify the `resource.id` property.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.
userID	string A user ID. Specifies the user that the authorization is scoped to. When a user authenticates with username and password, InfluxDB generates a user session with all the permissions specified by all the user's authorizations.

Responses

Request samples

Payload

Content type

application/json

Example

Creates an authorization.

{"description": "iot_users read buckets",
"orgID": "INFLUX_ORG_ID",
"permissions": [{"action": "read",
"resource": {"type": "buckets"
}
}
]
}

Response samples

201
400
401
500
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Delete an authorization

Deletes an authorization.

Use the endpoint to delete an API token.

If you want to disable an API token instead of delete it, update the authorization's status to inactive.

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "id must have a length of 16 bytes"
}

Retrieve an authorization

Retrieves an authorization.

Use this endpoint to retrieve information about an API token, including the token's permissions and the user that the token is scoped to.

InfluxDB OSS

InfluxDB OSS returns API token values in authorizations.
If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.

View tokens

View tokens

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Update an API token to be active or inactive

Updates an authorization.

Use this endpoint to set an API token's status to be active or inactive. InfluxDB rejects requests that use inactive API tokens.

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

An authorization ID. Specifies the authorization to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

In the request body, provide the authorization properties to update.

description	string A description of the token.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"status": "active"
}

Response samples

200
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Backup

Download snapshot of metadata stored in the server's embedded KV store. Don't use with InfluxDB versions greater than InfluxDB 2.1.x. Deprecated

Retrieves a snapshot of metadata stored in the server's embedded KV store. InfluxDB versions greater than 2.1.x don't include metadata stored in embedded SQL; avoid using this endpoint with versions greater than 2.1.x.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Download snapshot of all metadata in the server

Authorizations:

TokenAuthentication

header Parameters

Accept-Encoding	string Default: identity Enum: "gzip" "identity" Indicates the content encoding (usually a compression algorithm) that the client can understand.
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Download snapshot of all TSM data in a shard

Authorizations:

TokenAuthentication

path Parameters

shardID

required

integer <int64>

The shard ID.

query Parameters

since

string <date-time>

Examples:

since=2006-01-02T15:04:05Z07:00 - RFC3339 date/time format

The earliest time RFC3339 date/time format to include in the snapshot.

header Parameters

Accept-Encoding	string Default: identity Enum: "gzip" "identity" Indicates the content encoding (usually a compression algorithm) that the client can understand.
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Buckets

Store your data in InfluxDB buckets. A bucket is a named location where time series data is stored. All buckets have a retention period, a duration of time that each data point persists. InfluxDB drops all points with timestamps older than the bucket’s retention period. A bucket belongs to an organization.

Manage buckets

List buckets

Lists buckets.

InfluxDB retrieves buckets owned by the organization associated with the authorization (API token). To limit which buckets are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all buckets up to the default limit.

InfluxDB OSS

If you use an operator token to authenticate your request, InfluxDB retrieves resources for all organizations in the instance. To retrieve resources for only a specific organization, use the org parameter or the orgID parameter to specify the organization.

Required permissions

Action	Permission required
Retrieve user buckets	`read-buckets`
Retrieve system buckets	`read-orgs`

Manage buckets

Authorizations:

TokenAuthentication

query Parameters

after	string A resource ID to seek from. Returns records created after the specified record; results don't include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see Pagination.
id	string A bucket ID. Only returns the bucket with the specified ID.
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
name	string A bucket name. Only returns buckets with the specified name.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
org	string An organization name. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Lists buckets for the organization associated with the authorization (API token). InfluxDB OSS Lists buckets for the specified organization.
orgID	string An organization ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Lists buckets for the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or `orgID` parameter. Lists buckets for the specified organization.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: filter buckets by name

curl --request GET "http://localhost:8086/api/v2/buckets?name=_monitoring" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json"

Response samples

200
401
500
default

Content type

application/json

{"buckets": [{"createdAt": "2022-03-15T17:22:33.72617939Z",
"description": "System bucket for monitoring logs",
"id": "77ca9dace40a9bfc",
"labels": [ ],
"links": {"labels": "/api/v2/buckets/77ca9dace40a9bfc/labels",
"members": "/api/v2/buckets/77ca9dace40a9bfc/members",
"org": "/api/v2/orgs/INFLUX_ORG_ID",
"owners": "/api/v2/buckets/77ca9dace40a9bfc/owners",
"self": "/api/v2/buckets/77ca9dace40a9bfc",
"write": "/api/v2/write?org=ORG_ID&bucket=77ca9dace40a9bfc"
},
"name": "_monitoring",
"orgID": "INFLUX_ORG_ID",
"retentionRules": [{"everySeconds": 604800,
"type": "expire"
}
],
"schemaType": "implicit",
"type": "system",
"updatedAt": "2022-03-15T17:22:33.726179487Z"
}
],
"links": {"self": "/api/v2/buckets?descending=false&limit=20&name=_monitoring&offset=0&orgID=ORG_ID"
}
}

Create a bucket

Creates a bucket and returns the bucket resource. The default data retention period is 30 days.

InfluxDB OSS

A single InfluxDB OSS instance supports active writes or queries for approximately 20 buckets across all organizations at a given time. Reading or writing to more than 20 buckets at a time can adversely affect performance.

Limitations

InfluxDB Cloud Free Plan allows users to create up to two buckets. Exceeding the bucket quota will result in an HTTP 403 status code. For additional information regarding InfluxDB Cloud offerings, see InfluxDB Cloud Pricing.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The bucket to create.

description	string A description of the bucket.
name required	string The bucket name.
orgID required	string The organization ID. Specifies the organization that owns the bucket.
	Array of objects (RetentionRules) Retention rules to expire or retain data. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period. InfluxDB Cloud `retentionRules` is required. InfluxDB OSS `retentionRules` isn't required.
rp	string Default: "0" The retention policy for the bucket. For InfluxDB 1.x, specifies the duration of time that each data point in the retention policy persists. If you need compatibility with InfluxDB 1.x, specify a value for the `rp` property; otherwise, see the `retentionRules` property. Retention policy is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is retention period. The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period.
schemaType	string (SchemaType) Enum: "implicit" "explicit"

Responses

Request samples

Payload
cURL: create a bucket with retention period
cURL

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
],
"rp": "0",
"schemaType": "implicit"
}

Response samples

Content type

application/json

{"createdAt": "2022-08-03T23:04:41.073704121Z",
"description": "A bucket holding air sensor data",
"id": "37407e232b3911d8",
"labels": [ ],
"links": {"labels": "/api/v2/buckets/37407e232b3911d8/labels",
"members": "/api/v2/buckets/37407e232b3911d8/members",
"org": "/api/v2/orgs/INFLUX_ORG_ID",
"owners": "/api/v2/buckets/37407e232b3911d8/owners",
"self": "/api/v2/buckets/37407e232b3911d8",
"write": "/api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8"
},
"name": "air_sensor",
"orgID": "INFLUX_ORG_ID",
"retentionRules": [{"everySeconds": 2592000,
"type": "expire"
}
],
"schemaType": "implicit",
"type": "user",
"updatedAt": "2022-08-03T23:04:41.073704228Z"
}

Delete a bucket

Deletes a bucket and all associated records.

InfluxDB Cloud

Does the following when you send a delete request:
1. Validates the request and queues the delete.
2. Returns an HTTP 204 status code if queued; error otherwise.
3. Handles the delete asynchronously.

InfluxDB OSS

Validates the request, handles the delete synchronously, and then responds with success or failure.

Limitations

Only one bucket can be deleted per request.

Delete a bucket

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

Bucket ID. The ID of the bucket to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL

curl --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --header 'Accept: application/json'

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "id must have a length of 16 bytes"
}

Retrieve a bucket

Retrieves a bucket.

Use this endpoint to retrieve information for a specific bucket.

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
404
500
default

Content type

application/json

{"createdAt": "2022-08-03T23:04:41.073704121Z",
"description": "bucket for air sensor data",
"id": "37407e232b3911d8",
"labels": [ ],
"links": {"labels": "/api/v2/buckets/37407e232b3911d8/labels",
"members": "/api/v2/buckets/37407e232b3911d8/members",
"org": "/api/v2/orgs/INFLUX_ORG_ID",
"owners": "/api/v2/buckets/37407e232b3911d8/owners",
"self": "/api/v2/buckets/37407e232b3911d8",
"write": "/api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8"
},
"name": "air-sensor",
"orgID": "bea7ea952287f70d",
"retentionRules": [{"everySeconds": 2592000,
"type": "expire"
}
],
"schemaType": "implicit",
"type": "user",
"updatedAt": "2022-08-03T23:04:41.073704228Z"
}

Update a bucket

Updates a bucket.

Use this endpoint to update properties (name, description, and retentionRules) of a bucket.

InfluxDB Cloud

Requires the retentionRules property in the request body. If you don't provide retentionRules, InfluxDB responds with an HTTP 403 status code.

InfluxDB OSS

Doesn't require retentionRules.

Update a bucket

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The bucket ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The bucket update to apply.

description	string A description of the bucket.
name	string The name of the bucket.
	Array of objects (PatchRetentionRules) Updates to rules to expire or retain data. No rules means no updates.

Responses

Request samples

Payload
cURL

Content type

application/json

{"description": "string",
"name": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
]
}

Response samples

Content type

application/json

{"createdAt": "2022-08-03T23:04:41.073704121Z",
"description": "bucket holding air sensor data",
"id": "37407e232b3911d8",
"labels": [ ],
"links": {"labels": "/api/v2/buckets/37407e232b3911d8/labels",
"members": "/api/v2/buckets/37407e232b3911d8/members",
"org": "/api/v2/orgs/INFLUX_ORG_ID",
"owners": "/api/v2/buckets/37407e232b3911d8/owners",
"self": "/api/v2/buckets/37407e232b3911d8",
"write": "/api/v2/write?org=INFLUX_ORG_ID&bucket=37407e232b3911d8"
},
"name": "air_sensor",
"orgID": "INFLUX_ORG_ID",
"retentionRules": [{"everySeconds": 2592000,
"type": "expire"
}
],
"schemaType": "implicit",
"type": "user",
"updatedAt": "2022-08-07T22:49:49.422962913Z"
}

List all labels for a bucket

Lists all labels for a bucket.

Labels are objects that contain labelID, name, description, and color key-value pairs. They may be used for grouping and filtering InfluxDB resources. Labels are also capable of grouping across different resources--for example, you can apply a label named air_sensor to a bucket and a task to quickly organize resources.

Use the /api/v2/labels InfluxDB API endpoint to retrieve and manage labels.
Manage labels in the InfluxDB UI

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to retrieve labels for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"labels": [{"id": "09cbd068e7ebb000",
"name": "production_buckets",
"orgID": "INFLUX_ORG_ID"
}
],
"links": {"self": "/api/v2/labels"
}
}

Add a label to a bucket

Adds a label to a bucket and returns the new label information.

Labels are objects that contain labelID, name, description, and color key-value pairs. They may be used for grouping and filtering across one or more kinds of resources--for example, you can apply a label named air_sensor to a bucket and a task to quickly organize resources.

Limitations

Before adding a label to a bucket, you must create the label if you haven't already. To create a label with the InfluxDB API, send a POST request to the /api/v2/labels endpoint).

Use the /api/v2/labels InfluxDB API endpoint to retrieve and manage labels.
Manage labels in the InfluxDB UI

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

Bucket ID. The ID of the bucket to label.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

An object that contains a labelID to add to the bucket.

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload
cURL

Content type

application/json

{"labelID": "string"
}

Response samples

Content type

application/json

{"label": {"id": "09cbd068e7ebb000",
"name": "production_buckets",
"orgID": "INFLUX_ORG_ID"
},
"links": {"self": "/api/v2/labels"
}
}

Delete a label from a bucket

Authorizations:

TokenAuthentication

path Parameters

bucketID required	string The bucket ID.
labelID required	string The ID of the label to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all users with member privileges for a bucket

Lists all users for a bucket.

InfluxDB users have permission to access InfluxDB.

Members are users in an organization with access to the specified resource.

Use this endpoint to retrieve all users with access to a bucket.

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to retrieve users for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/buckets/37407e232b3911d8/members"
},
"users": [{"id": "791df274afd48a83",
"links": {"self": "/api/v2/users/791df274afd48a83"
},
"name": "example_user_1",
"role": "member",
"status": "active"
},
{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_2",
"role": "owner",
"status": "active"
}
]
}

Add a member to a bucket

Add a user to a bucket and return the new user information.

InfluxDB users have permission to access InfluxDB.

Members are users in an organization.

Use this endpoint to give a user member privileges to a bucket.

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to retrieve users for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A user to add as a member to the bucket.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload
cURL

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

Content type

application/json

{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_1",
"role": "member",
"status": "active"
}

Remove a member from a bucket

Removes a member from a bucket.

Use this endpoint to remove a user's member privileges from a bucket. This removes the user's read and write permissions for the bucket.

Authorizations:

TokenAuthentication

path Parameters

bucketID required	string The ID of the bucket to remove a user from.
userID required	string The ID of the user to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

List all owners of a bucket

Lists all owners of a bucket.

Bucket owners have permission to delete buckets and remove user and member permissions from the bucket.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Owner permissions are separate from API token permissions.
Owner permissions are used in the context of the InfluxDB UI.

Required permissions

read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve a list of owners for.

Authorizations

Manage users

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to retrieve owners for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/buckets/BUCKET_ID/owners"
},
"users": [{"id": "d88d182d91b0950f",
"links": {"self": "/api/v2/users/d88d182d91b0950f"
},
"name": "example-owner",
"role": "owner",
"status": "active"
}
]
}

Add an owner to a bucket

Adds an owner to a bucket and returns the owners with role and user detail.

Use this endpoint to create a resource owner for the bucket. Bucket owners have permission to delete buckets and remove user and member permissions from the bucket.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Owner permissions are separate from API token permissions.
Owner permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID
INFLUX_ORG_ID* is the ID of the organization that you want to add an owner for.

Authorizations

Manage users

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The ID of the bucket to add an owner for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A user to add as an owner for the bucket.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload
cURL

Content type

application/json

{"id": "d88d182d91b0950f",
"links": {"self": "/api/v2/users/d88d182d91b0950f"
},
"name": "example-user",
"role": "owner",
"status": "active"
}

Response samples

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}

Remove an owner from a bucket

Removes an owner from a bucket.

Use this endpoint to remove a user's owner role for a bucket.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Owner permissions are separate from API token permissions.
Owner permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Authorizations

Manage users

Authorizations:

TokenAuthentication

path Parameters

bucketID required	string The ID of the bucket to remove an owner from.
userID required	string The ID of the owner to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

Get buckets in a source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

query Parameters

org	string The name of the organization.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"buckets": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/buckets/1/labels",
"members": "/api/v2/buckets/1/members",
"org": "/api/v2/orgs/2",
"owners": "/api/v2/buckets/1/owners",
"self": "/api/v2/buckets/1",
"write": "/api/v2/write?org=2&bucket=1"
},
"name": "string",
"orgID": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
],
"rp": "string",
"schemaType": "implicit",
"type": "user",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Cells

Create a dashboard cell

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Cell that will be added

h	integer <int32>
name	string
usingView	string Makes a copy of the provided view.
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"h": 0,
"name": "string",
"usingView": "string",
"w": 0,
"x": 0,
"y": 0
}

Response samples

201
404
default

Content type

application/json

{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}

Replace cells in a dashboard

Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells.

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Array ()

h	integer <int32>
id	string
	object
viewID	string The reference to a view from the views API.
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

[{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
]

Response samples

201
404
default

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Delete a dashboard cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to delete.
dashboardID required	string The ID of the dashboard to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Update the non-positional information related to a cell

Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts.

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to update.
dashboardID required	string The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

h	integer <int32>
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"h": 0,
"w": 0,
"x": 0,
"y": 0
}

Response samples

200
404
default

Content type

application/json

{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}

Retrieve the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The cell ID.
dashboardID required	string The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to update.
dashboardID required	string The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

name

required

string

required

LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Checks

List all checks

Authorizations:

TokenAuthentication

query Parameters

limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
orgID required	string Only show checks that belong to a specific organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"checks": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"every": "string",
"level": "UNKNOWN",
"offset": "string",
"reportZero": true,
"staleTime": "string",
"statusMessageTemplate": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeSince": "string",
"type": "deadman"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add new check

Authorizations:

TokenAuthentication

Request Body schema: application/json

Check to create

description	string An optional description of the check.
	Array of objects (Labels)
name required	string
orgID required	string The ID of the organization that owns this check.
required	object (DashboardQuery)
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.
taskID	string The ID of the task associated with this check.
type required	string custom PostCheck Check threshold deadman custom

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"type": "custom"
}

Response samples

201
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "custom"
}

Delete a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "custom"
}

Update a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Check update to apply

description	string
name	string
status	string Enum: "active" "inactive"

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string",
"status": "active"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "custom"
}

Update a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Check update to apply

description	string An optional description of the check.
	Array of objects (Labels)
name required	string
orgID required	string The ID of the organization that owns this check.
required	object (DashboardQuery)
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.
taskID	string The ID of the task associated with this check.
type required	string custom PostCheck Check threshold deadman custom

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"type": "custom"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "custom"
}

List all labels for a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a check

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete label from a check

Authorizations:

TokenAuthentication

path Parameters

checkID required	string The check ID.
labelID required	string The ID of the label to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a check query

Authorizations:

TokenAuthentication

path Parameters

checkID

required

string

The check ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
404
default

Content type

application/json

{"flux": "string"
}

Config

Retrieve runtime configuration

Returns the active runtime configuration of the InfluxDB instance.

In InfluxDB v2.2+, use this endpoint to view your active runtime configuration, including flags and environment variables.

View your runtime server configuration

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
default

Content type

application/json

{"config": { }
}

Retrieve feature flags

Retrieves the feature flag key-value pairs configured for the InfluxDB instance. Feature flags are configuration options used to develop and test experimental InfluxDB features and are intended for internal use only.

This endpoint represents the first step in the following three-step process to configure feature flags:

Use token authentication or a user session with this endpoint to retrieve feature flags and their values.
Follow the instructions to enable, disable, or override values for feature flags.
Optional: To confirm that your change is applied, do one of the following:
- Send a request to this endpoint to retrieve the current feature flag values.
- Send a request to the GET /api/v2/config endpoint to retrieve the current runtime server configuration.

InfluxDB configuration options

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
500
default

Content type

application/json

{ }

Dashboards

List dashboards

Lists dashboards.

Manage dashboards.

Authorizations:

TokenAuthentication

query Parameters

descending	boolean Default: false
id	Array of strings A list of dashboard IDs. Returns only the specified dashboards. If you specify `id` and `owner`, only `id` is used.
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
org	string An organization name. Only returns dashboards that belong to the specified organization.
orgID	string An organization ID. Only returns dashboards that belong to the specified organization.
owner	string A user ID. Only returns dashboards where the specified user has the `owner` role.
sortBy	string Enum: "ID" "CreatedAt" "UpdatedAt" The column to sort by.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"dashboards": [{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Create a dashboard

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Dashboard to create

description	string The user-facing description of the dashboard.
name required	string The user-facing name of the dashboard.
orgID required	string The ID of the organization that owns the dashboard.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string"
}

Response samples

201
default

Content type

application/json

Example

{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Delete a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

query Parameters

include

string

Value: "properties"

If properties, includes the cell view properties in the response.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

Example

{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Update a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Patching of a dashboard

	object (schemas)
description	string optional, when provided will replace the description
name	string optional, when provided will replace the name

Responses

Request samples

Payload

Content type

application/json

{"cells": {"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0,
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
},
"description": "string",
"name": "string"
}

Response samples

200
404
default

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Create a dashboard cell

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Cell that will be added

h	integer <int32>
name	string
usingView	string Makes a copy of the provided view.
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"h": 0,
"name": "string",
"usingView": "string",
"w": 0,
"x": 0,
"y": 0
}

Response samples

201
404
default

Content type

application/json

{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}

Replace cells in a dashboard

Replaces all cells in a dashboard. This is used primarily to update the positional information of all cells.

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Array ()

h	integer <int32>
id	string
	object
viewID	string The reference to a view from the views API.
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

[{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
]

Response samples

201
404
default

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string",
"cells": [{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}
],
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"cells": "/api/v2/dashboards/1/cells",
"labels": "/api/v2/dashboards/1/labels",
"members": "/api/v2/dashboards/1/members",
"org": "/api/v2/labels/1",
"owners": "/api/v2/dashboards/1/owners",
"self": "/api/v2/dashboards/1"
},
"meta": {"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}

Delete a dashboard cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to delete.
dashboardID required	string The ID of the dashboard to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Update the non-positional information related to a cell

Updates the non positional information related to a cell. Updates to a single cell's positional data could cause grid conflicts.

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to update.
dashboardID required	string The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

h	integer <int32>
w	integer <int32>
x	integer <int32>
y	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"h": 0,
"w": 0,
"x": 0,
"y": 0
}

Response samples

200
404
default

Content type

application/json

{"h": 0,
"id": "string",
"links": {"self": "string",
"view": "string"
},
"viewID": "string",
"w": 0,
"x": 0,
"y": 0
}

Retrieve the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The cell ID.
dashboardID required	string The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to update.
dashboardID required	string The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

name

required

string

required

LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

List all labels for a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID required	string The dashboard ID.
labelID required	string The ID of the label to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all dashboard members

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}
]
}

Add a member to a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as member

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}

Remove a member from a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID required	string The dashboard ID.
userID required	string The ID of the member to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all dashboard owners

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}
]
}

Add an owner to a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID

required

string

The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as owner

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}

Remove an owner from a dashboard

Authorizations:

TokenAuthentication

path Parameters

dashboardID required	string The dashboard ID.
userID required	string The ID of the owner to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

DBRPs

The InfluxDB 1.x data model includes databases and retention policies. InfluxDB 2.x replaces databases and retention policies with buckets. To support InfluxDB 1.x query and write patterns in InfluxDB 2.x, databases and retention policies are mapped to buckets using the database and retention policy (DBRP) mapping service. The DBRP mapping service uses the database and retention policy specified in 1.x compatibility API requests to route operations to a bucket.

Database and retention policy mapping

List database retention policy mappings

Lists database retention policy (DBRP) mappings.

Database and retention policy mapping

Authorizations:

TokenAuthentication

query Parameters

bucketID	string A bucket ID. Only returns DBRP mappings that belong to the specified bucket.
db	string A database. Only returns DBRP mappings that belong to the 1.x database.
default	boolean Specifies filtering on default
id	string A DBPR mapping ID. Only returns the specified DBRP mapping.
org	string An organization name. Only returns DBRP mappings for the specified organization.
orgID	string An organization ID. Only returns DBRP mappings for the specified organization.
rp	string A retention policy. Specifies the 1.x retention policy to filter on.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
401
500
default

Content type

application/json

{"content": [{"bucketID": "4d4d9d5b61dee751",
"database": "example_database_1",
"default": true,
"id": "0a3cbb5dd526a000",
"orgID": "bea7ea952287f70d",
"retention_policy": "autogen"
},
{"bucketID": "4d4d9d5b61dee751",
"database": "example_database_2",
"default": false,
"id": "0a3cbcde20e38000",
"orgID": "bea7ea952287f70d",
"retention_policy": "example_retention_policy"
}
]
}

Add a database retention policy mapping

Creates a database retention policy (DBRP) mapping and returns the mapping.

Use this endpoint to add InfluxDB 1.x API compatibility to your InfluxDB Cloud or InfluxDB OSS 2.x buckets. Your buckets must contain a DBRP mapping in order to query and write using the InfluxDB 1.x API. object.

Database and retention policy mapping

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The database retention policy mapping to add.

Note that retention_policy is a required parameter in the request body. The value of retention_policy can be any arbitrary string name or value, with the default value commonly set as autogen. The value of retention_policy isn't a retention_policy

bucketID required	string A bucket ID. Identifies the bucket used as the target for the translation.
database required	string A database name. Identifies the InfluxDB v1 database.
default	boolean Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property's value).
org	string An organization name. Identifies the organization that owns the mapping.
orgID	string An organization ID. Identifies the organization that owns the mapping.
retention_policy required	string A retention policy name. Identifies the InfluxDB v1 retention policy mapping.

Responses

Request samples

Payload
cURL: create a database retention policy mapping

Content type

application/json

{"bucketID": "string",
"database": "string",
"default": true,
"org": "string",
"orgID": "string",
"retention_policy": "string"
}

Response samples

Content type

application/json

{"bucketID": "4d4d9d5b61dee751",
"database": "example_database",
"default": true,
"id": "0a3cbb5dd526a000",
"orgID": "bea7ea952287f70d",
"retention_policy": "autogen"
}

Delete a database retention policy

Deletes the specified database retention policy (DBRP) mapping.

Database and retention policy mapping

Authorizations:

TokenAuthentication

path Parameters

dbrpID

required

string

A DBRP mapping ID. Only returns the specified DBRP mapping.

query Parameters

org	string An organization name. Specifies the organization that owns the DBRP mapping.
orgID	string An organization ID. Specifies the organization that owns the DBRP mapping.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

The query parameters contain invalid values.

{"code": "invalid",
"message": "invalid ID"
}

Retrieve a database retention policy mapping

Retrieves the specified retention policy (DBRP) mapping.

Database and retention policy mapping

Authorizations:

TokenAuthentication

path Parameters

dbrpID

required

string

A DBRP mapping ID. Specifies the DBRP mapping.

query Parameters

org	string An organization name. Specifies the organization that owns the DBRP mapping.
orgID	string An organization ID. Specifies the organization that owns the DBRP mapping.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"content": {"bucketID": "4d4d9d5b61dee751",
"database": "example_database_1",
"default": true,
"id": "0a3cbb5dd526a000",
"orgID": "bea7ea952287f70d",
"retention_policy": "autogen"
}
}

Update a database retention policy mapping

Authorizations:

TokenAuthentication

path Parameters

dbrpID

required

string

A DBRP mapping ID. Specifies the DBRP mapping.

query Parameters

org	string An organization name. Specifies the organization that owns the DBRP mapping.
orgID	string An organization ID. Specifies the organization that owns the DBRP mapping.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Updates the database retention policy (DBRP) mapping and returns the mapping.

Use this endpoint to modify the retention policy (retention_policy property) of a DBRP mapping.

Database and retention policy mapping

default	boolean Set to `true` to use this DBRP mapping as the default retention policy for the database (specified by the `database` property's value). To remove the default mapping, set to `false`.
retention_policy	string A retention policy name. Identifies the InfluxDB v1 retention policy mapping.

Responses

Request samples

Payload
cURL: Update a DBRP mapping

Content type

application/json

{"default": true,
"retention_policy": "string"
}

Response samples

Content type

application/json

{"content": {"bucketID": "4d4d9d5b61dee751",
"database": "example_database",
"default": false,
"id": "0a3cbb5dd526a000",
"orgID": "bea7ea952287f70d",
"retention_policy": "example_retention_policy"
}
}

Debug

Generate profiling and trace reports.

Use routes under /debug/pprof to analyze the Go runtime of InfluxDB. These endpoints generate Go runtime profiles and trace reports. Profiles are collections of stack traces that show call sequences leading to instances of a particular event, such as allocation.

For more information about pprof profile and trace reports, see the following resources:

Retrieve all runtime profiles

Collects samples and returns reports for the following Go runtime profiles:

allocs: All past memory allocations
block: Stack traces that led to blocking on synchronization primitives
cpu: (Optional) Program counters sampled from the executing stack. Include by passing the cpu query parameter with a duration value. Equivalent to the report from GET /debug/pprof/profile?seconds=NUMBER_OF_SECONDS.
goroutine: All current goroutines
heap: Memory allocations for live objects
mutex: Holders of contended mutexes
threadcreate: Stack traces that led to the creation of new OS threads

Authorizations:

TokenAuthentication

query Parameters

cpu	string <duration> Collects and returns CPU profiling data for the specified duration. InfluxDB duration

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: Get all profiles
Shell: Get all profiles except CPU

# Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.

curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz

# x profiles/cpu.pb.gz
# x profiles/goroutine.pb.gz
# x profiles/block.pb.gz
# x profiles/mutex.pb.gz
# x profiles/heap.pb.gz
# x profiles/allocs.pb.gz
# x profiles/threadcreate.pb.gz

# Analyze a profile.

go tool pprof profiles/heap.pb.gz

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the memory allocations runtime profile

Returns a Go runtime profile report of all past memory allocations. allocs is the same as the heap profile, but changes the default pprof display to -alloc_space, the total number of bytes allocated since the program began (including garbage-collected bytes).

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/allocs

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

# At the prompt, get the top N memory allocations.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the block runtime profile

Collects samples and returns a Go runtime profile report of stack traces that led to blocking on synchronization primitives.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/block

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the command line invocation

Returns the command line that invoked InfluxDB.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the goroutines runtime profile

Collects statistics and returns a Go runtime profile report of all current goroutines.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as `human-readable text with comments that translate addresses to function names and line numbers for debugging.` `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/goroutine

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the heap runtime profile

Collects statistics and returns a Go runtime profile report of memory allocations for live objects.

To run garbage collection before sampling, pass the gc query parameter with a value of 1.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
gc	integer <int64> Enum: 0 1 `0`: (Default) don't force garbage collection before sampling. `1`: Force garbage collection before sampling.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/heap

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

# At the prompt, get the top N memory-intensive nodes.

(pprof) top10

# pprof displays the list:
#   Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total
#   Dropped 895 nodes (cum <= 0.83MB)
#   Showing top 10 nodes out of 143

Response samples

200
default

Content type

No sample

Retrieve the mutual exclusion (mutex) runtime profile

Collects statistics and returns a Go runtime profile report of lock contentions. The profile contains stack traces of holders of contended mutual exclusions (mutexes).

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/mutex

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the CPU runtime profile

Collects statistics and returns a Go runtime profile report of program counters on the executing stack.

Authorizations:

TokenAuthentication

query Parameters

seconds

string <int64>

Number of seconds to collect profile data. Default is 30 seconds.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Download the profile report.

curl http://localhost:8086/debug/pprof/profile -o cpu

# Analyze the profile in interactive mode.

go tool pprof ./cpu

# At the prompt, get the top N functions most often running
# or waiting during the sample period.

(pprof) top10

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve the threadcreate runtime profile

Collects statistics and returns a Go runtime profile report of stack traces that led to the creation of new OS threads.

Authorizations:

TokenAuthentication

query Parameters

debug	integer <int64> Enum: 0 1 `0`: (Default) Return the report as a gzip-compressed protocol buffer. `1`: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging. `debug=1` is mutually exclusive with the `seconds` query parameter.
seconds	string <int64> Number of seconds to collect statistics. `seconds` is mutually exclusive with `debug=1`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool pprof

# Analyze the profile in interactive mode.

go tool pprof http://localhost:8086/debug/pprof/threadcreate

# `pprof` returns the following prompt:
#   Entering interactive mode (type "help" for commands, "o" for options)
#   (pprof)

#  At the prompt, get the top N entries.

(pprof) top10

Response samples

200
default

Content type

No sample

Retrieve the runtime execution trace

Collects profile data and returns trace execution events for the current program.

Authorizations:

TokenAuthentication

query Parameters

seconds

string <int64>

Number of seconds to collect profile data.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

Shell: go tool trace

# Download the trace file.

curl http://localhost:8086/debug/pprof/trace -o trace

# Analyze the trace.

go tool trace ./trace

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Delete

Delete data from an InfluxDB bucket.

Delete data

Deletes data from a bucket.

Use this endpoint to delete points from a bucket in a specified time range.

InfluxDB Cloud

Does the following when you send a delete request:
1. Validates the request and queues the delete.
2. If queued, responds with success (HTTP 2xx status code); error otherwise.
3. Handles the delete asynchronously and reaches eventual consistency.

To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

Validates the request, handles the delete synchronously, and then responds with success or failure.

Required permissions

write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Delete data
Learn how to use delete predicate syntax.
Learn how InfluxDB handles deleted tags and deleted fields.

Authorizations:

TokenAuthentication

query Parameters

bucket	string A bucket name or ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence.
bucketID	string A bucket ID. Specifies the bucket to delete data from. If you pass both `bucket` and `bucketID`, `bucketID` takes precedence.
org	string An organization name or ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Deletes data from the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. Deletes data from the bucket in the specified organization. If you pass both `orgID` and `org`, they must both be valid.
orgID	string An organization ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Deletes data from the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. Deletes data from the bucket in the specified organization. If you pass both `orgID` and `org`, they must both be valid.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Time range parameters and an optional delete predicate expression.

To select points to delete within the specified time range, pass a delete predicate expression in the predicate property of the request body. If you don't pass a predicate, InfluxDB deletes all data with timestamps in the specified time range.

Delete data
Learn how to use delete predicate syntax.

predicate	string An expression in delete predicate syntax.
start required	string <date-time> A timestamp (RFC3339 date/time format). The earliest time to delete from.
stop required	string <date-time> A timestamp (RFC3339 date/time format). The latest time to delete from.

Responses

Request samples

Payload
cURL

Content type

application/json

{"predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")",
"start": "2019-08-24T14:15:22Z",
"stop": "2019-08-24T14:15:22Z"
}

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

Health

Retrieve the health of the instance

Returns the health of the instance.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
503
default

Content type

application/json

{"checks": [{ }
],
"commit": "string",
"message": "string",
"name": "string",
"status": "pass",
"version": "string"
}

Labels

List all labels

Authorizations:

TokenAuthentication

query Parameters

orgID

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
500
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Create a label

Authorizations:

TokenAuthentication

Request Body schema: application/json

The label to create.

name required	string
orgID required	string
	object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}

Response samples

201
500
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label

Authorizations:

TokenAuthentication

path Parameters

labelID

required

string

The ID of the label to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

Retrieve a label

Authorizations:

TokenAuthentication

path Parameters

labelID

required

string

The ID of the label to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
500
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Update a label

Authorizations:

TokenAuthentication

path Parameters

labelID

required

string

The ID of the label to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A label update.

name	string
	object

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}

Response samples

200
401
404
500
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Legacy Authorizations

List all legacy authorizations

Authorizations:

TokenAuthentication

query Parameters

authID	string An authorization ID. Returns the specified legacy authorization.
org	string An organization name. Only returns legacy authorizations that belong to the specified organization.
orgID	string An organization ID. Only returns legacy authorizations that belong to the specified organization.
token	string An authorization name token. Only returns legacy authorizations with the specified name.
user	string A user name. Only returns legacy authorizations scoped to the specified user.
userID	string A user ID. Only returns legacy authorizations scoped to the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"authorizations": [{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Create a legacy authorization

Creates a legacy authorization and returns the legacy authorization.

Required permissions

write-users USER_ID if you pass the userID property in the request body.

USER_ID is the ID of the user that you want to scope the authorization to.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The legacy authorization to create.

description	string A description of the token.
orgID required	string The organization ID. Identifies the organization that the authorization is scoped to.
required	Array of objects (Permission) non-empty The list of permissions that provide `read` and `write` access to organization resources. An authorization must contain at least one permission.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.
token	string The name that you provide for the authorization.
userID	string The user ID. Identifies the user that the authorization is scoped to.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"status": "active",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"userID": "string"
}

Response samples

201
400
401
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Delete a legacy authorization

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

The ID of the legacy authorization to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a legacy authorization

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

The ID of the legacy authorization to get.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Update a legacy authorization to be active or inactive

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

The ID of the legacy authorization to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Legacy authorization to update

description	string A description of the token.
status	string Default: "active" Enum: "active" "inactive" Status of the token. If `inactive`, InfluxDB rejects requests that use the token.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"status": "active"
}

Response samples

200
default

Content type

application/json

{"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
}

Set a legacy authorization password

Authorizations:

TokenAuthentication

path Parameters

authID

required

string

The ID of the legacy authorization to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

New password

password

required

string

Responses

Request samples

Payload

Content type

application/json

{"password": "string"
}

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Legacy Query

Query with the 1.x compatibility API

Queries InfluxDB using InfluxQL.

Authorizations:

TokenAuthentication

query Parameters

db required	string The database to query data from. This is mapped to an InfluxDB bucket. For more information, see Database and retention policy mapping.
epoch	string Enum: "ns" "u" "µ" "ms" "s" "m" "h" A unix timestamp precision. Formats timestamps as unix (epoch) timestamps the specified precision instead of RFC3339 timestamps with nanosecond precision.
p	string The InfluxDB 1.x password to authenticate the request.
q required	string The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon (`;`).
rp	string The retention policy to query data from. This is mapped to an InfluxDB bucket. For more information, see Database and retention policy mapping.
u	string The InfluxDB 1.x username to authenticate the request.

header Parameters

Accept	string Default: application/json Enum: "application/json" "application/csv" "text/csv" "application/x-msgpack" Media type that the client can understand. Note: With `application/csv`, query results include unix timestamps instead of RFC3339 timestamps.
Accept-Encoding	string Default: identity Enum: "gzip" "identity" The content encoding (usually a compression algorithm) that the client can understand.
Content-Type	string Value: "application/json"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Responses

Response samples

200
default

Content type

No sample

Legacy Write

Write time series data into InfluxDB in a V1-compatible format

Authorizations:

TokenAuthentication

query Parameters

db required	string Bucket to write to. If none exists, InfluxDB creates a bucket with a default 3-day retention policy.
p	string The InfluxDB 1.x password to authenticate the request.
precision	string Write precision.
rp	string Retention policy name.
u	string The InfluxDB 1.x username to authenticate the request.

header Parameters

Content-Encoding	string Default: identity Enum: "gzip" "identity" When present, its value indicates to the database that compression is applied to the line protocol body.
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

Line protocol body

string

Responses

Response samples

400
401
403
413
default

Content type

application/json

{"code": "internal error",
"err": "string",
"line": 0,
"message": "string",
"op": "string"
}

Metrics

Retrieve workload performance metrics

Returns metrics about the workload performance of an InfluxDB instance.

Use this endpoint to get performance, resource, and usage metrics.

For the list of metrics categories, see InfluxDB OSS metrics.
Learn how to use InfluxDB to scrape Prometheus metrics.
Learn how InfluxDB parses the Prometheus exposition format.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

text/plain

# HELP go_threads Number of OS threads created.
# TYPE go_threads gauge
go_threads 19
# HELP http_api_request_duration_seconds Time taken to respond to HTTP request
# TYPE http_api_request_duration_seconds histogram
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.005"} 4
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.01"} 4
http_api_request_duration_seconds_bucket{handler="platform",method="GET",path="/:fallback_path",response_code="200",status="2XX",user_agent="curl",le="0.025"} 5

NotificationEndpoints

List all notification endpoints

Authorizations:

TokenAuthentication

query Parameters

limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
orgID required	string Only show notification endpoints that belong to specific organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
},
"notificationEndpoints": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "slack",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"token": "string",
"url": "string"
}
]
}

Add a notification endpoint

Authorizations:

TokenAuthentication

Request Body schema: application/json

Notification endpoint to create

authMethod required	string Enum: "none" "basic" "bearer"
contentTemplate	string
description	string An optional description of the notification endpoint.
	object Customized headers.
id	string
	Array of objects (Labels)
method required	string Enum: "POST" "GET" "PUT"
name required	string
orgID	string
password	string
status	string Default: "active" Enum: "active" "inactive" The status of the endpoint.
token	string
type required	string (NotificationEndpointType) http PostNotificationEndpoint NotificationEndpoint slack pagerduty http telegram
url required	string
userID	string
username	string

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"id": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

Response samples

201
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

Delete a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

Update a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Check update to apply

description	string
name	string
status	string Enum: "active" "inactive"

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string",
"status": "active"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

Update a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A new notification endpoint to replace the existing endpoint with

authMethod required	string Enum: "none" "basic" "bearer"
contentTemplate	string
description	string An optional description of the notification endpoint.
	object Customized headers.
id	string
	Array of objects (Labels)
method required	string Enum: "POST" "GET" "PUT"
name required	string
orgID	string
password	string
status	string Default: "active" Enum: "active" "inactive" The status of the endpoint.
token	string
type required	string (NotificationEndpointType) http PostNotificationEndpoint NotificationEndpoint slack pagerduty http telegram
url required	string
userID	string
username	string

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"id": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "http",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"authMethod": "none",
"contentTemplate": "string",
"headers": {"property1": "string",
"property2": "string"
},
"method": "POST",
"password": "string",
"token": "string",
"url": "string",
"username": "string"
}

List all labels for a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID

required

string

The notification endpoint ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a notification endpoint

Authorizations:

TokenAuthentication

path Parameters

endpointID required	string The notification endpoint ID.
labelID required	string The ID of the label to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

NotificationRules

List all notification rules

Authorizations:

TokenAuthentication

query Parameters

checkID	string Only show notifications that belong to the specific check ID.
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
orgID required	string Only show notification rules that belong to a specific organization ID.
tag	string^[a-zA-Z0-9_]+:[a-zA-Z0-9_]+$ Example: tag=env:prod Only return notification rules that "would match" statuses which contain the tag key value pairs provided.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
},
"notificationRules": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"endpointID": "string",
"every": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"limit": 0,
"limitEvery": 0,
"links": {"labels": "/api/v2/notificationRules/1/labels",
"members": "/api/v2/notificationRules/1/members",
"owners": "/api/v2/notificationRules/1/owners",
"query": "/api/v2/notificationRules/1/query",
"self": "/api/v2/notificationRules/1"
},
"name": "string",
"offset": "string",
"orgID": "string",
"ownerID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"channel": "string",
"messageTemplate": "string",
"type": "slack"
}
]
}

Add a notification rule

Authorizations:

TokenAuthentication

Request Body schema: application/json

Notification rule to create

description	string An optional description of the notification rule.
endpointID required	string
every	string The notification repetition interval.
	Array of objects (Labels)
limit	integer Don't notify me more than times every seconds. If set, limitEvery cannot be empty.
limitEvery	integer Don't notify me more than times every seconds. If set, limit cannot be empty.
name required	string Human-readable name describing the notification rule.
offset	string Duration to delay after the schedule, before executing check.
orgID required	string The ID of the organization that owns this notification rule.
runbookLink	string
sleepUntil	string
status required	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.
required	Array of objects (StatusRule) non-empty List of status rules the notification rule attempts to match.
	Array of objects (TagRule) List of tag rules the notification rule attempts to match.
taskID	string The ID of the task associated with this notification rule.
type required	string http PostNotificationRule NotificationRule telegram smtp slack pagerduty http
url	string

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"endpointID": "string",
"every": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"limit": 0,
"limitEvery": 0,
"name": "string",
"offset": "string",
"orgID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"type": "http",
"url": "string"
}

Response samples

201
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"endpointID": "string",
"every": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"limit": 0,
"limitEvery": 0,
"links": {"labels": "/api/v2/notificationRules/1/labels",
"members": "/api/v2/notificationRules/1/members",
"owners": "/api/v2/notificationRules/1/owners",
"query": "/api/v2/notificationRules/1/query",
"self": "/api/v2/notificationRules/1"
},
"name": "string",
"offset": "string",
"orgID": "string",
"ownerID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "http",
"url": "string"
}

Delete a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"endpointID": "string",
"every": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"limit": 0,
"limitEvery": 0,
"links": {"labels": "/api/v2/notificationRules/1/labels",
"members": "/api/v2/notificationRules/1/members",
"owners": "/api/v2/notificationRules/1/owners",
"query": "/api/v2/notificationRules/1/query",
"self": "/api/v2/notificationRules/1"
},
"name": "string",
"offset": "string",
"orgID": "string",
"ownerID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "http",
"url": "string"
}

Update a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Notification rule update to apply

description	string
name	string
status	string Enum: "active" "inactive"

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string",
"status": "active"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"endpointID": "string",
"every": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"limit": 0,
"limitEvery": 0,
"links": {"labels": "/api/v2/notificationRules/1/labels",
"members": "/api/v2/notificationRules/1/members",
"owners": "/api/v2/notificationRules/1/owners",
"query": "/api/v2/notificationRules/1/query",
"self": "/api/v2/notificationRules/1"
},
"name": "string",
"offset": "string",
"orgID": "string",
"ownerID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "http",
"url": "string"
}

Update a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Notification rule update to apply

description	string An optional description of the notification rule.
endpointID required	string
every	string The notification repetition interval.
	Array of objects (Labels)
limit	integer Don't notify me more than times every seconds. If set, limitEvery cannot be empty.
limitEvery	integer Don't notify me more than times every seconds. If set, limit cannot be empty.
name required	string Human-readable name describing the notification rule.
offset	string Duration to delay after the schedule, before executing check.
orgID required	string The ID of the organization that owns this notification rule.
runbookLink	string
sleepUntil	string
status required	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.
required	Array of objects (StatusRule) non-empty List of status rules the notification rule attempts to match.
	Array of objects (TagRule) List of tag rules the notification rule attempts to match.
taskID	string The ID of the task associated with this notification rule.
type required	string http PostNotificationRule NotificationRule telegram smtp slack pagerduty http
url	string

Responses

Request samples

Payload

Content type

application/json

Example

{"description": "string",
"endpointID": "string",
"every": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"limit": 0,
"limitEvery": 0,
"name": "string",
"offset": "string",
"orgID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"type": "http",
"url": "string"
}

Response samples

200
404
default

Content type

application/json

Example

{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"endpointID": "string",
"every": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"limit": 0,
"limitEvery": 0,
"links": {"labels": "/api/v2/notificationRules/1/labels",
"members": "/api/v2/notificationRules/1/members",
"owners": "/api/v2/notificationRules/1/owners",
"query": "/api/v2/notificationRules/1/query",
"self": "/api/v2/notificationRules/1"
},
"name": "string",
"offset": "string",
"orgID": "string",
"ownerID": "string",
"runbookLink": "string",
"sleepUntil": "string",
"status": "active",
"statusRules": [{"count": 0,
"currentLevel": "UNKNOWN",
"period": "string",
"previousLevel": "UNKNOWN"
}
],
"tagRules": [{"key": "string",
"operator": "equal",
"value": "string"
}
],
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"type": "http",
"url": "string"
}

List all labels for a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a notification rule

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete label from a notification rule

Authorizations:

TokenAuthentication

path Parameters

labelID required	string The ID of the label to delete.
ruleID required	string The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Organizations

Create and manage your organizations. An organization is a workspace for a group of users. Organizations can be used to separate different environments, projects, teams or users within InfluxDB.

Use the /api/v2/orgs endpoints to create, view, and manage organizations.

List organizations

Lists organizations.

To limit which organizations are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all organizations up to the default limit.

InfluxDB Cloud

Only returns the organization that owns the token passed in the request.

View organizations

Authorizations:

TokenAuthentication

query Parameters

descending	boolean Default: false
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.
org	string An organization name. Only returns the specified organization.
orgID	string An organization ID. Only returns the specified organization.
userID	string A user ID. Only returns organizations where the specified user is a member or owner.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/orgs"
},
"orgs": [{"createdAt": "2022-07-17T23:00:30.778487Z",
"description": "Example InfluxDB organization",
"id": "INFLUX_ORG_ID",
"links": {"buckets": "/api/v2/buckets?org=INFLUX_ORG",
"dashboards": "/api/v2/dashboards?org=INFLUX_ORG",
"labels": "/api/v2/orgs/INFLUX_ORG_ID/labels",
"logs": "/api/v2/orgs/INFLUX_ORG_ID/logs",
"members": "/api/v2/orgs/INFLUX_ORG_ID/members",
"owners": "/api/v2/orgs/INFLUX_ORG_ID/owners",
"secrets": "/api/v2/orgs/INFLUX_ORG_ID/secrets",
"self": "/api/v2/orgs/INFLUX_ORG_ID",
"tasks": "/api/v2/tasks?org=InfluxData"
},
"name": "INFLUX_ORG",
"updatedAt": "2022-07-17T23:00:30.778487Z"
}
]
}

Create an organization

Creates an organization and returns the newly created organization.

InfluxDB Cloud

Doesn't allow you to use this endpoint to create organizations.

Manage organizations

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The organization to create.

description	string The description of the organization.
name required	string The name of the organization.

Responses

Request samples

Payload
cURL

Content type

application/json

{"description": "string",
"name": "string"
}

Response samples

Content type

application/json

{"createdAt": "2022-08-24T23:05:52.881317Z",
"description": "",
"id": "INFLUX_ORG_ID",
"links": {"buckets": "/api/v2/buckets?org=INFLUX_ORG",
"dashboards": "/api/v2/dashboards?org=INFLUX_ORG",
"labels": "/api/v2/orgs/INFLUX_ORG_ID/labels",
"logs": "/api/v2/orgs/INFLUX_ORG_ID/logs",
"members": "/api/v2/orgs/INFLUX_ORG_ID/members",
"owners": "/api/v2/orgs/INFLUX_ORG_ID/owners",
"secrets": "/api/v2/orgs/INFLUX_ORG_ID/secrets",
"self": "/api/v2/orgs/INFLUX_ORG_ID",
"tasks": "/api/v2/tasks?org=INFLUX_ORG"
},
"name": "INFLUX_ORG",
"updatedAt": "2022-08-24T23:05:52.881318Z"
}

Delete an organization

Deletes an organization.

Deleting an organization from InfluxDB Cloud can't be undone. Once deleted, all data associated with the organization is removed.

InfluxDB Cloud

Does the following when you send a delete request:
1. Validates the request and queues the delete.
2. Returns an HTTP 204 status code if queued; error otherwise.
3. Handles the delete asynchronously.

InfluxDB OSS

Validates the request, handles the delete synchronously, and then responds with success or failure.

Limitations

Only one organization can be deleted per request.

Delete organizations

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

Retrieve an organization

Retrieves an organization.

Use this endpoint to retrieve information for a specific organization.

View organizations

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
404
500
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"defaultStorageType": "tsm",
"description": "string",
"id": "string",
"links": {"buckets": "/api/v2/buckets?org=myorg",
"dashboards": "/api/v2/dashboards?org=myorg",
"labels": "/api/v2/orgs/1/labels",
"members": "/api/v2/orgs/1/members",
"owners": "/api/v2/orgs/1/owners",
"secrets": "/api/v2/orgs/1/secrets",
"self": "/api/v2/orgs/1",
"tasks": "/api/v2/tasks?org=myorg"
},
"name": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update an organization

Updates an organization.

Use this endpoint to update properties (name, description) of an organization.

Updating an organization’s name affects all resources that reference the organization by name, including the following:

Queries
Dashboards
Tasks
Telegraf configurations
Templates

If you change an organization name, be sure to update the organization name in these resources as well.

Update an organization

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The organization update to apply.

description	string The description of the organization.
name	string The name of the organization.

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string"
}

Response samples

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"defaultStorageType": "tsm",
"description": "string",
"id": "string",
"links": {"buckets": "/api/v2/buckets?org=myorg",
"dashboards": "/api/v2/dashboards?org=myorg",
"labels": "/api/v2/orgs/1/labels",
"members": "/api/v2/orgs/1/members",
"owners": "/api/v2/orgs/1/owners",
"secrets": "/api/v2/orgs/1/secrets",
"self": "/api/v2/orgs/1",
"tasks": "/api/v2/tasks?org=myorg"
},
"name": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

List all members of an organization

Lists all users that belong to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Member permissions are separate from API token permissions.
Member permissions are used in the context of the InfluxDB UI.

Required permissions

read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve members for.

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to retrieve users for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"links": {"self": "/api/v2/orgs/055aa4783aa38398/members"
},
"users": [{"id": "791df274afd48a83",
"links": {"self": "/api/v2/users/791df274afd48a83"
},
"name": "example_user_1",
"role": "member",
"status": "active"
},
{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_2",
"role": "owner",
"status": "active"
}
]
}

Add a member to an organization

Add a user to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Member permissions are separate from API token permissions.
Member permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to add a member to.

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The user to add to the organization.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload
cURL

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

Content type

application/json

{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_1",
"role": "member",
"status": "active"
}

Remove a member from an organization

Removes a member from an organization.

Use this endpoint to remove a user's member privileges for an organization. Removing member privileges removes the user's read and write permissions from the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Member permissions are separate from API token permissions.
Member permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Manage members

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The ID of the organization to remove a user from.
userID required	string The ID of the user to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

List all owners of an organization

Lists all owners of an organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Required permissions

read-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to retrieve a list of owners from.

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization to list owners for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"links": {"self": "/api/v2/orgs/055aa4783aa38398/owners"
},
"users": [{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_2",
"role": "owner",
"status": "active"
}
]
}

Add an owner to an organization

Adds an owner to an organization.

Use this endpoint to assign the organization owner role to a user.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to add an owner for.

Authorizations

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The ID of the organization that you want to add an owner for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The user to add as an owner of the organization.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload
cURL

Content type

application/json

{"id": "09cfb87051cbe000",
"links": {"self": "/api/v2/users/09cfb87051cbe000"
},
"name": "example_user_1",
"role": "owner",
"status": "active"
}

Response samples

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}

Remove an owner from an organization

Removes an owner from the organization.

Organization owners have permission to delete organizations and remove user and member permissions from the organization.

InfluxDB Cloud

Doesn't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Limitations

Owner permissions are separate from API token permissions.
Owner permissions are used in the context of the InfluxDB UI.

Required permissions

write-orgs INFLUX_ORG_ID

INFLUX_ORG_ID is the ID of the organization that you want to remove an owner from.

Authorizations

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The ID of the organization to remove an owner from.
userID required	string The ID of the user to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

401
404
500
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

Ping

Get the status of the instance

Retrieves the status and InfluxDB version of the instance.

Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP 204 status code to inform you the instance is available.

InfluxDB Cloud

Isn't versioned and doesn't return X-Influxdb-Version in the headers.

Influx ping

Authorizations:

TokenAuthentication

Responses

Request samples

cURL

curl --request GET "http://localhost:8086/ping"

Get the status of the instance

Returns the status and InfluxDB version of the instance.

Use this endpoint to monitor uptime for the InfluxDB instance. The response returns a HTTP 204 status code to inform you the instance is available.

InfluxDB Cloud

Isn't versioned and doesn't return X-Influxdb-Version in the headers.

Influx ping

Authorizations:

TokenAuthentication

Responses

Request samples

cURL

curl --request HEAD "http://localhost:8086/ping"

Query

Retrieve data, analyze queries, and get query suggestions.

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.

Authorizations:

TokenAuthentication

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 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 Requires either the `org` parameter or `orgID` parameter. Queries the bucket in the specified organization.

header Parameters

Accept-Encoding	string Default: identity Enum: "gzip" "identity" The content encoding (usually a compression algorithm) that the client can understand.
Content-Type	string Enum: "application/json" "application/vnd.flux"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema:
application/json
application/json
application/vnd.flux

Flux query or specification to execute

	object (Dialect) Options for tabular data output. Default output is annotated CSV with headers. For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.
	object (File) Represents a source from a single file
now	string <date-time> Specifies the time that should be reported as `now` in the query. Default is the server `now` time.
query required	string The query script to execute.
type	string Value: "flux" The type of query. Must be "flux".

Responses

Request samples

Payload
cURL

Content type

{"dialect": {"annotations": ["group"
],
"commentPrefix": "#",
"dateTimeFormat": "RFC3339",
"delimiter": ",",
"header": true
},
"extern": {"body": [{"text": "string",
"type": "string"
}
],
"imports": [{"as": {"name": "string",
"type": "string"
},
"path": {"type": "string",
"value": "string"
},
"type": "string"
}
],
"name": "string",
"package": {"name": {"name": "string",
"type": "string"
},
"type": "string"
},
"type": "string"
},
"now": "2019-08-24T14:15:22Z",
"query": "string",
"type": "flux"
}

Response samples

Content type

application/csv

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

Analyze a Flux query

Analyzes a Flux query 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.

Authorizations:

TokenAuthentication

header Parameters

Content-Type	string Value: "application/json"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: application/json

Flux query to analyze

	object (Dialect) Options for tabular data output. Default output is annotated CSV with headers. For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.
	object (File) Represents a source from a single file
now	string <date-time> Specifies the time that should be reported as `now` in the query. Default is the server `now` time.
query required	string The query script to execute.
type	string Value: "flux" The type of query. Must be "flux".

Responses

Request samples

Payload
cURL: Analyze a Flux query

Content type

application/json

{"dialect": {"annotations": ["group"
],
"commentPrefix": "#",
"dateTimeFormat": "RFC3339",
"delimiter": ",",
"header": true
},
"extern": {"body": [{"text": "string",
"type": "string"
}
],
"imports": [{"as": {"name": "string",
"type": "string"
},
"path": {"type": "string",
"value": "string"
},
"type": "string"
}
],
"name": "string",
"package": {"name": {"name": "string",
"type": "string"
},
"type": "string"
},
"type": "string"
},
"now": "2019-08-24T14:15:22Z",
"query": "string",
"type": "flux"
}

Response samples

200
400
default

Content type

application/json

Returns an error object if the Flux query is missing a property key.

The following sample query is missing the bucket property key:

{
  "query": "from(: \"iot_center\")\
  ...
}

{"errors": [{"character": 0,
"column": 6,
"line": 1,
"message": "missing property key"
}
]
}

Generate a query Abstract Syntax Tree (AST)

Analyzes a Flux query and returns a complete package source 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.

Authorizations:

TokenAuthentication

header Parameters

Content-Type	string Value: "application/json"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: application/json

The Flux query to analyze.

query

required

string

The Flux query script to be analyzed.

Responses

Request samples

Payload
cURL: Analyze and generate AST for the query

Content type

application/json

{"query": "string"
}

Response samples

200
400
default

Content type

application/json

{"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"
}
}

List Flux query suggestions

Lists Flux query suggestions. Each suggestion contains a Flux function 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.

List of all Flux functions

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL

curl --request GET "INFLUX_URL/api/v2/query/suggestions" \
  --header "Accept: application/json" \
  --header "Authorization: Token INFLUX_API_TOKEN"

Response samples

200
301
default

Content type

application/json

{"funcs": [{"name": "_fillEmpty",
"params": {"createEmpty": "bool",
"tables": "stream"
}
},
{"name": "_highestOrLowest",
"params": {"_sortLimit": "function",
"column": "invalid",
"groupColumns": "array",
"n": "invalid",
"reducer": "function",
"tables": "stream"
}
},
{"name": "_hourSelection",
"params": {"location": "object",
"start": "int",
"stop": "int",
"tables": "stream",
"timeColumn": "string"
}
},
{"name": "_sortLimit",
"params": {"columns": "array",
"desc": "bool",
"n": "int",
"tables": "stream"
}
},
{"name": "_window",
"params": {"createEmpty": "bool",
"every": "duration",
"location": "object",
"offset": "duration",
"period": "duration",
"startColumn": "string",
"stopColumn": "string",
"tables": "stream",
"timeColumn": "string"
}
},
{"name": "aggregateWindow",
"params": {"column": "invalid",
"createEmpty": "bool",
"every": "duration",
"fn": "function",
"location": "object",
"offset": "duration",
"period": "duration",
"tables": "stream",
"timeDst": "string",
"timeSrc": "string"
}
},
{"name": "bool",
"params": {"v": "invalid"
}
},
{"name": "bottom",
"params": {"columns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "buckets",
"params": {"host": "string",
"org": "string",
"orgID": "string",
"token": "string"
}
},
{"name": "bytes",
"params": {"v": "invalid"
}
},
{"name": "cardinality",
"params": {"bucket": "string",
"bucketID": "string",
"host": "string",
"org": "string",
"orgID": "string",
"predicate": "function",
"start": "invalid",
"stop": "invalid",
"token": "string"
}
},
{"name": "chandeMomentumOscillator",
"params": {"columns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "columns",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "contains",
"params": {"set": "array",
"value": "invalid"
}
},
{"name": "count",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "cov",
"params": {"on": "array",
"pearsonr": "bool",
"x": "invalid",
"y": "invalid"
}
},
{"name": "covariance",
"params": {"columns": "array",
"pearsonr": "bool",
"tables": "stream",
"valueDst": "string"
}
},
{"name": "cumulativeSum",
"params": {"columns": "array",
"tables": "stream"
}
},
{"name": "derivative",
"params": {"columns": "array",
"initialZero": "bool",
"nonNegative": "bool",
"tables": "stream",
"timeColumn": "string",
"unit": "duration"
}
},
{"name": "die",
"params": {"msg": "string"
}
},
{"name": "difference",
"params": {"columns": "array",
"initialZero": "bool",
"keepFirst": "bool",
"nonNegative": "bool",
"tables": "stream"
}
},
{"name": "display",
"params": {"v": "invalid"
}
},
{"name": "distinct",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "doubleEMA",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "drop",
"params": {"columns": "array",
"fn": "function",
"tables": "stream"
}
},
{"name": "duplicate",
"params": {"as": "string",
"column": "string",
"tables": "stream"
}
},
{"name": "duration",
"params": {"v": "invalid"
}
},
{"name": "elapsed",
"params": {"columnName": "string",
"tables": "stream",
"timeColumn": "string",
"unit": "duration"
}
},
{"name": "exponentialMovingAverage",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "fill",
"params": {"column": "string",
"tables": "stream",
"usePrevious": "bool",
"value": "invalid"
}
},
{"name": "filter",
"params": {"fn": "function",
"onEmpty": "string",
"tables": "stream"
}
},
{"name": "findColumn",
"params": {"column": "string",
"fn": "function",
"tables": "stream"
}
},
{"name": "findRecord",
"params": {"fn": "function",
"idx": "int",
"tables": "stream"
}
},
{"name": "first",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "float",
"params": {"v": "invalid"
}
},
{"name": "from",
"params": {"bucket": "string",
"bucketID": "string",
"host": "string",
"org": "string",
"orgID": "string",
"token": "string"
}
},
{"name": "getColumn",
"params": {"column": "string"
}
},
{"name": "getRecord",
"params": {"idx": "int"
}
},
{"name": "group",
"params": {"columns": "array",
"mode": "string",
"tables": "stream"
}
},
{"name": "highestAverage",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "highestCurrent",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "highestMax",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "histogram",
"params": {"bins": "array",
"column": "string",
"countColumn": "string",
"normalize": "bool",
"tables": "stream",
"upperBoundColumn": "string"
}
},
{"name": "histogramQuantile",
"params": {"countColumn": "string",
"minValue": "float",
"quantile": "float",
"tables": "stream",
"upperBoundColumn": "string",
"valueColumn": "string"
}
},
{"name": "holtWinters",
"params": {"column": "string",
"interval": "duration",
"n": "int",
"seasonality": "int",
"tables": "stream",
"timeColumn": "string",
"withFit": "bool"
}
},
{"name": "hourSelection",
"params": {"location": "object",
"start": "int",
"stop": "int",
"tables": "stream",
"timeColumn": "string"
}
},
{"name": "increase",
"params": {"columns": "array",
"tables": "stream"
}
},
{"name": "int",
"params": {"v": "invalid"
}
},
{"name": "integral",
"params": {"column": "string",
"interpolate": "string",
"tables": "stream",
"timeColumn": "string",
"unit": "duration"
}
},
{"name": "join",
"params": {"method": "string",
"on": "array",
"tables": "invalid"
}
},
{"name": "kaufmansAMA",
"params": {"column": "string",
"n": "int",
"tables": "stream"
}
},
{"name": "kaufmansER",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "keep",
"params": {"columns": "array",
"fn": "function",
"tables": "stream"
}
},
{"name": "keyValues",
"params": {"keyColumns": "array",
"tables": "stream"
}
},
{"name": "keys",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "last",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "length",
"params": {"arr": "array"
}
},
{"name": "limit",
"params": {"n": "int",
"offset": "int",
"tables": "stream"
}
},
{"name": "linearBins",
"params": {"count": "int",
"infinity": "bool",
"start": "float",
"width": "float"
}
},
{"name": "logarithmicBins",
"params": {"count": "int",
"factor": "float",
"infinity": "bool",
"start": "float"
}
},
{"name": "lowestAverage",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "lowestCurrent",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "lowestMin",
"params": {"column": "string",
"groupColumns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "map",
"params": {"fn": "function",
"mergeKey": "bool",
"tables": "stream"
}
},
{"name": "max",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "mean",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "median",
"params": {"column": "string",
"compression": "float",
"method": "string",
"tables": "stream"
}
},
{"name": "min",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "mode",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "movingAverage",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "now",
"params": { }
},
{"name": "pearsonr",
"params": {"on": "array",
"x": "invalid",
"y": "invalid"
}
},
{"name": "pivot",
"params": {"columnKey": "array",
"rowKey": "array",
"tables": "stream",
"valueColumn": "string"
}
},
{"name": "quantile",
"params": {"column": "string",
"compression": "float",
"method": "string",
"q": "float",
"tables": "stream"
}
},
{"name": "range",
"params": {"start": "invalid",
"stop": "invalid",
"tables": "stream"
}
},
{"name": "reduce",
"params": {"fn": "function",
"identity": "invalid",
"tables": "stream"
}
},
{"name": "relativeStrengthIndex",
"params": {"columns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "rename",
"params": {"columns": "invalid",
"fn": "function",
"tables": "stream"
}
},
{"name": "sample",
"params": {"column": "string",
"n": "int",
"pos": "int",
"tables": "stream"
}
},
{"name": "set",
"params": {"key": "string",
"tables": "stream",
"value": "string"
}
},
{"name": "skew",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "sort",
"params": {"columns": "array",
"desc": "bool",
"tables": "stream"
}
},
{"name": "spread",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "stateCount",
"params": {"column": "string",
"fn": "function",
"tables": "stream"
}
},
{"name": "stateDuration",
"params": {"column": "string",
"fn": "function",
"tables": "stream",
"timeColumn": "string",
"unit": "duration"
}
},
{"name": "stateTracking",
"params": {"countColumn": "string",
"durationColumn": "string",
"durationUnit": "duration",
"fn": "function",
"tables": "stream",
"timeColumn": "string"
}
},
{"name": "stddev",
"params": {"column": "string",
"mode": "string",
"tables": "stream"
}
},
{"name": "string",
"params": {"v": "invalid"
}
},
{"name": "sum",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "tableFind",
"params": {"fn": "function",
"tables": "stream"
}
},
{"name": "tail",
"params": {"n": "int",
"offset": "int",
"tables": "stream"
}
},
{"name": "time",
"params": {"v": "invalid"
}
},
{"name": "timeShift",
"params": {"columns": "array",
"duration": "duration",
"tables": "stream"
}
},
{"name": "timeWeightedAvg",
"params": {"tables": "stream",
"unit": "duration"
}
},
{"name": "timedMovingAverage",
"params": {"column": "string",
"every": "duration",
"period": "duration",
"tables": "stream"
}
},
{"name": "to",
"params": {"bucket": "string",
"bucketID": "string",
"fieldFn": "function",
"host": "string",
"measurementColumn": "string",
"org": "string",
"orgID": "string",
"tables": "stream",
"tagColumns": "array",
"timeColumn": "string",
"token": "string"
}
},
{"name": "toBool",
"params": {"tables": "stream"
}
},
{"name": "toFloat",
"params": {"tables": "stream"
}
},
{"name": "toInt",
"params": {"tables": "stream"
}
},
{"name": "toString",
"params": {"tables": "stream"
}
},
{"name": "toTime",
"params": {"tables": "stream"
}
},
{"name": "toUInt",
"params": {"tables": "stream"
}
},
{"name": "today",
"params": { }
},
{"name": "top",
"params": {"columns": "array",
"n": "int",
"tables": "stream"
}
},
{"name": "tripleEMA",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "tripleExponentialDerivative",
"params": {"n": "int",
"tables": "stream"
}
},
{"name": "truncateTimeColumn",
"params": {"tables": "stream",
"timeColumn": "invalid",
"unit": "duration"
}
},
{"name": "uint",
"params": {"v": "invalid"
}
},
{"name": "union",
"params": {"tables": "array"
}
},
{"name": "unique",
"params": {"column": "string",
"tables": "stream"
}
},
{"name": "wideTo",
"params": {"bucket": "string",
"bucketID": "string",
"host": "string",
"org": "string",
"orgID": "string",
"tables": "stream",
"token": "string"
}
},
{"name": "window",
"params": {"createEmpty": "bool",
"every": "duration",
"location": "object",
"offset": "duration",
"period": "duration",
"startColumn": "string",
"stopColumn": "string",
"tables": "stream",
"timeColumn": "string"
}
},
{"name": "yield",
"params": {"name": "string",
"tables": "stream"
}
}
]
}

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.

List of all Flux functions

Authorizations:

TokenAuthentication

path Parameters

name

required

string

A Flux function name.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL

curl --request GET "INFLUX_URL/api/v2/query/suggestions/sum/" \
  --header "Accept: application/json" \
  --header "Authorization: Token INFLUX_API_TOKEN"

Response samples

200
500

Content type

application/json

{"name": "sum",
"params": {"column": "string",
"tables": "stream"
}
}

Ready

Get the readiness of an instance at startup

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"started": "2019-03-13T10:09:33.891196-04:00",
"status": "ready",
"up": "14m45.911966424s"
}

RemoteConnections

List all remote connections

Authorizations:

TokenAuthentication

query Parameters

name	string
orgID required	string The organization ID.
remoteURL	string <uri>

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"remotes": [{"allowInsecureTLS": false,
"description": "string",
"id": "string",
"name": "string",
"orgID": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}
]
}

Register a new remote connection

Authorizations:

TokenAuthentication

Request Body schema: application/json

allowInsecureTLS required	boolean Default: false
description	string
name required	string
orgID required	string
remoteAPIToken required	string
remoteOrgID	string
remoteURL required	string <uri>

Responses

Request samples

Payload

Content type

application/json

{"allowInsecureTLS": false,
"description": "string",
"name": "string",
"orgID": "string",
"remoteAPIToken": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}

Response samples

201
400
default

Content type

application/json

{"allowInsecureTLS": false,
"description": "string",
"id": "string",
"name": "string",
"orgID": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}

Delete a remote connection

Authorizations:

TokenAuthentication

path Parameters

remoteID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a remote connection

Authorizations:

TokenAuthentication

path Parameters

remoteID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"allowInsecureTLS": false,
"description": "string",
"id": "string",
"name": "string",
"orgID": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}

Update a remote connection

Authorizations:

TokenAuthentication

path Parameters

remoteID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

allowInsecureTLS	boolean Default: false
description	string
name	string
remoteAPIToken	string
remoteOrgID	string
remoteURL	string <uri>

Responses

Request samples

Payload

Content type

application/json

{"allowInsecureTLS": false,
"description": "string",
"name": "string",
"remoteAPIToken": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}

Response samples

200
400
404
default

Content type

application/json

{"allowInsecureTLS": false,
"description": "string",
"id": "string",
"name": "string",
"orgID": "string",
"remoteOrgID": "string",
"remoteURL": "http://example.com"
}

Replications

List all replications

Authorizations:

TokenAuthentication

query Parameters

localBucketID	string
name	string
orgID required	string The organization ID.
remoteID	string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"replications": [{"currentQueueSizeBytes": 0,
"description": "string",
"dropNonRetryableData": true,
"id": "string",
"latestErrorMessage": "string",
"latestResponseCode": 0,
"localBucketID": "string",
"maxQueueSizeBytes": 0,
"name": "string",
"orgID": "string",
"remainingBytesToBeSynced": 0,
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}
]
}

Register a new replication

Authorizations:

TokenAuthentication

query Parameters

validate

boolean

Default: false

If true, validate the replication, but don't save it.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

description	string
dropNonRetryableData	boolean Default: false
localBucketID required	string
maxAgeSeconds required	integer <int64> >= 0 Default: 604800
maxQueueSizeBytes required	integer <int64> >= 33554430 Default: 67108860
name required	string
orgID required	string
remoteBucketID	string
remoteBucketName	string
remoteID required	string

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"dropNonRetryableData": false,
"localBucketID": "string",
"maxAgeSeconds": 604800,
"maxQueueSizeBytes": 67108860,
"name": "string",
"orgID": "string",
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}

Response samples

201
400
default

Content type

application/json

{"currentQueueSizeBytes": 0,
"description": "string",
"dropNonRetryableData": true,
"id": "string",
"latestErrorMessage": "string",
"latestResponseCode": 0,
"localBucketID": "string",
"maxQueueSizeBytes": 0,
"name": "string",
"orgID": "string",
"remainingBytesToBeSynced": 0,
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}

Delete a replication

Authorizations:

TokenAuthentication

path Parameters

replicationID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a replication

Authorizations:

TokenAuthentication

path Parameters

replicationID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"currentQueueSizeBytes": 0,
"description": "string",
"dropNonRetryableData": true,
"id": "string",
"latestErrorMessage": "string",
"latestResponseCode": 0,
"localBucketID": "string",
"maxQueueSizeBytes": 0,
"name": "string",
"orgID": "string",
"remainingBytesToBeSynced": 0,
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}

Update a replication

Authorizations:

TokenAuthentication

path Parameters

replicationID

required

string

query Parameters

validate

boolean

Default: false

If true, validate the updated information, but don't save it.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

description	string
dropNonRetryableData	boolean
maxAgeSeconds	integer <int64> >= 0
maxQueueSizeBytes	integer <int64> >= 33554430
name	string
remoteBucketID	string
remoteBucketName	string
remoteID	string

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"dropNonRetryableData": true,
"maxAgeSeconds": 0,
"maxQueueSizeBytes": 33554430,
"name": "string",
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}

Response samples

200
400
404
default

Content type

application/json

{"currentQueueSizeBytes": 0,
"description": "string",
"dropNonRetryableData": true,
"id": "string",
"latestErrorMessage": "string",
"latestResponseCode": 0,
"localBucketID": "string",
"maxQueueSizeBytes": 0,
"name": "string",
"orgID": "string",
"remainingBytesToBeSynced": 0,
"remoteBucketID": "string",
"remoteBucketName": "string",
"remoteID": "string"
}

Validate a replication

Authorizations:

TokenAuthentication

path Parameters

replicationID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Resources

List all known resources

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

["string"
]

Restore

Overwrite storage metadata for a bucket with shard info from a backup. Deprecated

Authorizations:

TokenAuthentication

path Parameters

bucketID

required

string

The bucket ID.

header Parameters

Content-Type	string Default: application/octet-stream Value: "application/octet-stream"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

Database info serialized as protobuf.

string <byte>

Responses

Response samples

200
default

Content type

application/json

"string"

Create a new bucket pre-seeded with shard info from a backup.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Metadata manifest for a bucket.

bucketID required	string
bucketName required	string
defaultRetentionPolicy required	string
description	string
organizationID required	string
organizationName required	string
required	Array of objects (RetentionPolicyManifests)

Responses

Request samples

Payload

Content type

application/json

{"bucketID": "string",
"bucketName": "string",
"defaultRetentionPolicy": "string",
"description": "string",
"organizationID": "string",
"organizationName": "string",
"retentionPolicies": [{"duration": 0,
"name": "string",
"replicaN": 0,
"shardGroupDuration": 0,
"shardGroups": [{"deletedAt": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z",
"id": 0,
"shards": [{"id": 0,
"shardOwners": [{"nodeID": 0
}
]
}
],
"startTime": "2019-08-24T14:15:22Z",
"truncatedAt": "2019-08-24T14:15:22Z"
}
],
"subscriptions": [{"destinations": ["string"
],
"mode": "string",
"name": "string"
}
]
}
]
}

Response samples

201
default

Content type

application/json

{"id": "string",
"name": "string",
"shardMappings": [{"newId": 0,
"oldId": 0
}
]
}

Overwrite the embedded KV store on the server with a backed-up snapshot.

Authorizations:

TokenAuthentication

header Parameters

Content-Encoding	string Default: identity Enum: "gzip" "identity" The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip payload, send `Content-Encoding: gzip` as a request header.
Content-Type	string Default: application/octet-stream Value: "application/octet-stream"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

Full KV snapshot.

string <binary>

Responses

Response samples

200
default

Content type

application/json

{"token": "string"
}

Restore a TSM snapshot into a shard.

Authorizations:

TokenAuthentication

path Parameters

shardID

required

string

The shard ID.

header Parameters

Content-Encoding	string Default: identity Enum: "gzip" "identity" The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip payload, send `Content-Encoding: gzip` as a request header.
Content-Type	string Default: application/octet-stream Value: "application/octet-stream"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

TSM snapshot.

string <binary>

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Overwrite the embedded SQL store on the server with a backed-up snapshot.

Authorizations:

TokenAuthentication

header Parameters

Content-Encoding	string Default: identity Enum: "gzip" "identity" The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip-compressed payload, send `Content-Encoding: gzip` as a request header.
Content-Type	string Default: application/octet-stream Value: "application/octet-stream"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

Full SQL snapshot.

string <binary>

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Routes

List all top level routes

Retrieves all the top level routes for the InfluxDB API.

Limitations

Only returns top level routes--for example, the response contains "tasks":"/api/v2/tasks", and doesn't contain resource-specific routes for tasks (/api/v2/tasks/TASK_ID/...).

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200

Content type

application/json

{"authorizations": "http://example.com",
"buckets": "http://example.com",
"dashboards": "http://example.com",
"external": {"statusFeed": "http://example.com"
},
"flags": "http://example.com",
"me": "http://example.com",
"orgs": "http://example.com",
"query": {"analyze": "http://example.com",
"ast": "http://example.com",
"self": "http://example.com",
"suggestions": "http://example.com"
},
"setup": "http://example.com",
"signin": "http://example.com",
"signout": "http://example.com",
"sources": "http://example.com",
"system": {"debug": "http://example.com",
"health": "http://example.com",
"metrics": "http://example.com"
},
"tasks": "http://example.com",
"telegrafs": "http://example.com",
"users": "http://example.com",
"variables": "http://example.com",
"write": "http://example.com"
}

Rules

Retrieve a notification rule query

Authorizations:

TokenAuthentication

path Parameters

ruleID

required

string

The notification rule ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
404
default

Content type

application/json

{"flux": "string"
}

Scraper Targets

List all scraper targets

Authorizations:

TokenAuthentication

query Parameters

id	Array of strings List of scraper target IDs to return. If both `id` and `owner` are specified, only `id` is used.
name	string Specifies the name of the scraper target.
org	string Specifies the organization name of the scraper target.
orgID	string Specifies the organization ID of the scraper target.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200

Content type

application/json

{"configurations": [{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics",
"bucket": "string",
"id": "string",
"links": {"bucket": "/api/v2/buckets/1",
"members": "/api/v2/scrapers/1/members",
"organization": "/api/v2/orgs/1",
"owners": "/api/v2/scrapers/1/owners",
"self": "/api/v2/scrapers/1"
},
"org": "string"
}
]
}

Create a scraper target

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Scraper target to create

allowInsecure	boolean Default: false Skip TLS verification on endpoint.
bucketID	string The ID of the bucket to write to.
name	string The name of the scraper target.
orgID	string The organization ID.
type	string Value: "prometheus" The type of the metrics to be parsed.
url	string The URL of the metrics endpoint.

Responses

Request samples

Payload

Content type

application/json

{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics"
}

Response samples

201
default

Content type

application/json

{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics",
"bucket": "string",
"id": "string",
"links": {"bucket": "/api/v2/buckets/1",
"members": "/api/v2/scrapers/1/members",
"organization": "/api/v2/orgs/1",
"owners": "/api/v2/scrapers/1/owners",
"self": "/api/v2/scrapers/1"
},
"org": "string"
}

Delete a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The identifier of the scraper target.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The identifier of the scraper target.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics",
"bucket": "string",
"id": "string",
"links": {"bucket": "/api/v2/buckets/1",
"members": "/api/v2/scrapers/1/members",
"organization": "/api/v2/orgs/1",
"owners": "/api/v2/scrapers/1/owners",
"self": "/api/v2/scrapers/1"
},
"org": "string"
}

Update a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The identifier of the scraper target.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Scraper target update to apply

allowInsecure	boolean Default: false Skip TLS verification on endpoint.
bucketID	string The ID of the bucket to write to.
name	string The name of the scraper target.
orgID	string The organization ID.
type	string Value: "prometheus" The type of the metrics to be parsed.
url	string The URL of the metrics endpoint.

Responses

Request samples

Payload

Content type

application/json

{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics"
}

Response samples

200
default

Content type

application/json

{"allowInsecure": false,
"bucketID": "string",
"name": "string",
"orgID": "string",
"type": "prometheus",
"url": "http://localhost:9090/metrics",
"bucket": "string",
"id": "string",
"links": {"bucket": "/api/v2/buckets/1",
"members": "/api/v2/scrapers/1/members",
"organization": "/api/v2/orgs/1",
"owners": "/api/v2/scrapers/1/owners",
"self": "/api/v2/scrapers/1"
},
"org": "string"
}

List all labels for a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a scraper target

Authorizations:

TokenAuthentication

path Parameters

labelID required	string The label ID.
scraperTargetID required	string The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all users with member privileges for a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}
]
}

Add a member to a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as member

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}

Remove a member from a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID required	string The scraper target ID.
userID required	string The ID of member to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all owners of a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}
]
}

Add an owner to a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID

required

string

The scraper target ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as owner

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}

Remove an owner from a scraper target

Authorizations:

TokenAuthentication

path Parameters

scraperTargetID required	string The scraper target ID.
userID required	string The ID of owner to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Secrets

List all secret keys for an organization

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"secrets": ["string"
],
"links": {"org": "string",
"self": "string"
}
}

Update secrets in an organization

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Secret key value pairs to update/add

property name*

string

Responses

Request samples

Payload

Content type

application/json

{"apikey": "abc123xyz"
}

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Delete a secret from an organization

Authorizations:

TokenAuthentication

path Parameters

orgID required	string The organization ID.
secretID required	string The secret ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Delete secrets from an organization Deprecated

Authorizations:

TokenAuthentication

path Parameters

orgID

required

string

The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Secret key to delete

secrets

Array of strings

Responses

Request samples

Payload

Content type

application/json

{"secrets": ["string"
]
}

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Setup

Check if database has default user, org, bucket

Returns true if no default user, organization, or bucket has been created.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200

Content type

application/json

{"allowed": true
}

Set up initial user, org and bucket

Post an onboarding request to set up initial user, org and bucket.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Source to create

bucket required	string
org required	string
password	string
retentionPeriodHrs	integer Deprecated Retention period in nanoseconds for the new bucket. This key's name has been misleading since OSS 2.0 GA, please transition to use `retentionPeriodSeconds`
retentionPeriodSeconds	integer <int64>
token	string Authentication token to set on the initial user. If not specified, the server will generate a token.
username required	string

Responses

Request samples

Payload

Content type

application/json

{"bucket": "string",
"org": "string",
"password": "string",
"retentionPeriodHrs": 0,
"retentionPeriodSeconds": 0,
"token": "string",
"username": "string"
}

Response samples

201
default

Content type

application/json

{"auth": {"description": "string",
"status": "active",
"createdAt": "2019-08-24T14:15:22Z",
"id": "string",
"links": {"self": "/api/v2/authorizations/1",
"user": "/api/v2/users/12"
},
"org": "string",
"orgID": "string",
"permissions": [{"action": "read",
"resource": {"id": "string",
"name": "string",
"org": "string",
"orgID": "string",
"type": "authorizations"
}
}
],
"token": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"user": "string",
"userID": "string"
},
"bucket": {"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/buckets/1/labels",
"members": "/api/v2/buckets/1/members",
"org": "/api/v2/orgs/2",
"owners": "/api/v2/buckets/1/owners",
"self": "/api/v2/buckets/1",
"write": "/api/v2/write?org=2&bucket=1"
},
"name": "string",
"orgID": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
],
"rp": "string",
"schemaType": "implicit",
"type": "user",
"updatedAt": "2019-08-24T14:15:22Z"
},
"org": {"createdAt": "2019-08-24T14:15:22Z",
"defaultStorageType": "tsm",
"description": "string",
"id": "string",
"links": {"buckets": "/api/v2/buckets?org=myorg",
"dashboards": "/api/v2/dashboards?org=myorg",
"labels": "/api/v2/orgs/1/labels",
"members": "/api/v2/orgs/1/members",
"owners": "/api/v2/orgs/1/owners",
"secrets": "/api/v2/orgs/1/secrets",
"self": "/api/v2/orgs/1",
"tasks": "/api/v2/tasks?org=myorg"
},
"name": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
},
"user": {"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}
}

Signin

Create a user session.

Authenticates Basic authentication credentials for a user, and then, if successful, generates a user session.

To authenticate a user, pass the HTTP Authorization header with the Basic scheme and the base64-encoded username and password. For syntax and more information, see Basic Authentication for syntax and more information.

If authentication is successful, InfluxDB creates a new session for the user and then returns the session cookie in the Set-Cookie response header.

InfluxDB stores user sessions in memory only. They expire within ten minutes and during restarts of the InfluxDB instance.

User sessions with authorizations

In InfluxDB Cloud, a user session inherits all the user's permissions for the organization.
In InfluxDB OSS, a user session inherits all the user's permissions for all the organizations that the user belongs to.

Signout

Authorizations:

BasicAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: signin with --user option encoding

curl --request POST http://localhost:8086/api/v2/signin \
     --user "USERNAME:PASSWORD"

Response samples

401
403
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Signout

Expire a user session

Expires a user session specified by a session cookie.

Use this endpoint to expire a user session that was generated when the user authenticated with the InfluxDB Developer Console (UI) or the POST /api/v2/signin endpoint.

For example, the POST /api/v2/signout endpoint represents the third step in the following three-step process to authenticate a user, retrieve the user resource, and then expire the session:

Send a request with the user's Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
Send a request to the GET /api/v2/me endpoint, passing the stored session cookie from step 1 to retrieve user information.
Send a request to the POST /api/v2/signout endpoint, passing the stored session cookie to expire the session.

See the complete example in request samples.

InfluxDB stores user sessions in memory only. If a user doesn't sign out, then the user session automatically expires within ten minutes or during a restart of the InfluxDB instance.

To learn more about cookies in HTTP requests, see Mozilla Developer Network (MDN) Web Docs, HTTP cookies.

Signin

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: sign in a user, verify the user session, and then end the session

# The following example shows how to use cURL and the InfluxDB API
# to do the following:
# 1. Sign in a user with a username and password.
# 2. Check that the user session exists for the user.
# 3. Sign out the user to expire the session.
# 4. Check that the session is no longer active.

# 1. Send a request to `POST /api/v2/signin` to sign in the user.
#    In your request, pass the following:
#
#      - `--user` option with basic authentication credentials.
#      - `-c` option with a file path where cURL will write cookies.

      curl --request POST \
        -c ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/signin" \
        --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}"

# 2. To check that a user session exists for the user in step 1,
#    send a request to `GET /api/v2/me`.
#    In your request, pass the `-b` option with the session cookie file path from step 1.

      curl --request GET \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/me"

#    InfluxDB responds with the `user` resource.

# 3. Send a request to `POST /api/v2/signout` to expire the user session.
#    In your request, pass the `-b` option with the session cookie file path from step 1.

      curl --request POST \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/signout"

#     If the user session is successfully expired, InfluxDB responds with
      an HTTP `204` status code.

# 4. To check that the user session is expired, call `GET /api/v2/me` again,
#    passing the `-b` option with the cookie file path.

      curl --request GET \
        -b ./cookie-file.tmp \
        "$INFLUX_URL/api/v2/me"

#    If the user session is expired, InfluxDB responds with an HTTP `401` status code.

Response samples

401
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Sources

List all sources

Authorizations:

TokenAuthentication

query Parameters

org	string The name of the organization.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"sources": [{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"languages": ["flux"
],
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}
]
}

Create a source

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Source to create

default	boolean
defaultRP	string
id	string
insecureSkipVerify	boolean
	object
metaUrl	string <uri>
name	string
orgID	string
password	string
sharedSecret	string
telegraf	string
token	string
type	string Enum: "v1" "v2" "self"
url	string <uri>
username	string

Responses

Request samples

Payload

Content type

application/json

{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}

Response samples

201
default

Content type

application/json

{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"languages": ["flux"
],
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}

Delete a source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"languages": ["flux"
],
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}

Update a Source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Source update

default	boolean
defaultRP	string
id	string
insecureSkipVerify	boolean
	object
metaUrl	string <uri>
name	string
orgID	string
password	string
sharedSecret	string
telegraf	string
token	string
type	string Enum: "v1" "v2" "self"
url	string <uri>
username	string

Responses

Request samples

Payload

Content type

application/json

{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}

Response samples

200
404
default

Content type

application/json

{"default": true,
"defaultRP": "string",
"id": "string",
"insecureSkipVerify": true,
"languages": ["flux"
],
"links": {"buckets": "string",
"health": "string",
"query": "string",
"self": "string"
},
"metaUrl": "http://example.com",
"name": "string",
"orgID": "string",
"password": "string",
"sharedSecret": "string",
"telegraf": "string",
"token": "string",
"type": "v1",
"url": "http://example.com",
"username": "string"
}

Get buckets in a source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

query Parameters

org	string The name of the organization.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"buckets": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/buckets/1/labels",
"members": "/api/v2/buckets/1/members",
"org": "/api/v2/orgs/2",
"owners": "/api/v2/buckets/1/owners",
"self": "/api/v2/buckets/1",
"write": "/api/v2/write?org=2&bucket=1"
},
"name": "string",
"orgID": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
],
"rp": "string",
"schemaType": "implicit",
"type": "user",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Get the health of a source

Authorizations:

TokenAuthentication

path Parameters

sourceID

required

string

The source ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
503
default

Content type

application/json

{"checks": [{ }
],
"commit": "string",
"message": "string",
"name": "string",
"status": "pass",
"version": "string"
}

Tasks

Process and analyze your data with tasks in the InfluxDB task engine. Use the /api/v2/tasks endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.

To configure a task, provide the script and the schedule to run the task. For examples, see how to create a task with the POST /api/v2/tasks endpoint.

Properties

A task object contains information about an InfluxDB task resource.

The following table defines the properties that appear in a task object:

authorizationID	string An authorization ID. Specifies the authorization used when the task communicates with the query engine. To find an authorization ID, use the `GET /api/v2/authorizations` endpoint to list authorizations.
createdAt	string <date-time>
cron	string A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.
description	string A description of the task.
every	string <duration> The interval (duration literal) at which the task runs. `every` also determines when the task first runs, depending on the specified time.
flux required	string <flux> The Flux script that the task executes.
id required	string
	Array of objects (Labels)
lastRunError	string
lastRunStatus	string Enum: "failed" "success" "canceled"
latestCompleted	string <date-time> A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.
	object
name required	string The name of the task.
offset	string <duration> A duration to delay execution of the task after the scheduled time has elapsed. `0` removes the offset.
org	string An organization name. Specifies the organization that owns the task.
orgID required	string An organization ID. Specifies the organization that owns the task.
ownerID	string A user ID. Specifies the owner of the task. To find a user ID, you can use the `GET /api/v2/users` endpoint to list users.
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.
updatedAt	string <date-time>

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

List tasks

Retrieves a list of tasks.

To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default limit.

Process data with InfluxDB tasks

Authorizations:

TokenAuthentication

query Parameters

after	string A task ID. Only returns tasks created after the specified task.
limit	integer [ 1 .. 500 ] Default: 100 The maximum number of tasks to return. Default is `100`. The minimum is `1` and the maximum is `500`. To reduce the payload size, combine `type=basic` and `limit` (see Request samples). For more information about the `basic` response, see the `type` parameter.
name	string A task name. Only returns tasks with the specified name. Different tasks may have the same name.
org	string An organization name. Only returns tasks owned by the specified organization.
orgID	string An organization ID. Only returns tasks owned by the specified organization.
status	string Enum: "active" "inactive" A task status. Only returns tasks that have the specified status (`active` or `inactive`).
type	string Default: "" Enum: "basic" "system" A task type (`basic` or `system`). Default is `system`. Specifies the level of detail for tasks in the response. The default (`system`) response contains all the metadata properties for tasks. To reduce the response size, pass `basic` to omit some task properties (`flux`, `createdAt`, `updatedAt`).
user	string A user ID. Only returns tasks owned by the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

cURL: all tasks, basic output

curl https://localhost:8086/api/v2/tasks/?limit=-1&type=basic \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token INFLUX_API_TOKEN'

Response samples

200
401
500
default

Content type

application/json

Example

A sample response body for the ?type=basic parameter. type=basic omits some task fields (createdAt and updatedAt) and field values (org, flux) in the response.

{"links": {"self": "/api/v2/tasks?limit=100"
},
"tasks": [{"every": "30m",
"flux": "",
"id": "09956cbb6d378000",
"labels": [ ],
"lastRunStatus": "success",
"latestCompleted": "2022-06-30T15:00:00Z",
"links": {"labels": "/api/v2/tasks/09956cbb6d378000/labels",
"logs": "/api/v2/tasks/09956cbb6d378000/logs",
"members": "/api/v2/tasks/09956cbb6d378000/members",
"owners": "/api/v2/tasks/09956cbb6d378000/owners",
"runs": "/api/v2/tasks/09956cbb6d378000/runs",
"self": "/api/v2/tasks/09956cbb6d378000"
},
"name": "task1",
"org": "",
"orgID": "48c88459ee424a04",
"ownerID": "0772396d1f411000",
"status": "active"
}
]
}

Create a task

Creates a task and returns the task.

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The task to create.

description	string An optional description of the task.
flux required	string The Flux script to run for this task.
org	string The name of the organization that owns this Task.
orgID	string The ID of the organization that owns this Task.
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Payload
cURL: create a task

Content type

application/json

{"description": "string",
"flux": "string",
"org": "string",
"orgID": "string",
"status": "active"
}

Response samples

201
400
401
500
default

Content type

application/json

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete a task

Deletes a task and associated records.

Use this endpoint to delete a task and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task.

If you want to disable a task instead of delete it, update the task status to inactive.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

Retrieve a task

Retrieves a task.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to retrieve.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update a task

Updates a task and then cancels all scheduled runs of the task.

Use this endpoint to set, modify, and clear task properties (for example: cron, name, flux, status). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task.

To update a task, pass an object that contains the updated key-value pairs. To activate or inactivate a task, set the status property. "status": "inactive" cancels scheduled runs and prevents manual runs of the task.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

An object that contains updated task properties to apply.

cron	string Update the 'cron' option in the flux script.
description	string Update the description of the task.
every	string Update the 'every' option in the flux script.
flux	string The Flux script that the task runs.
name	string Update the 'name' option in the flux script.
offset	string Update the 'offset' option in the flux script.
status	string (TaskStatusType) Enum: "active" "inactive" `inactive` cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Payload

Content type

application/json

{"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"name": "string",
"offset": "string",
"status": "active"
}

Response samples

Content type

application/json

{"authorizationID": "string",
"createdAt": "2019-08-24T14:15:22Z",
"cron": "string",
"description": "string",
"every": "string",
"flux": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/tasks/1/labels",
"logs": "/api/v2/tasks/1/logs",
"members": "/api/v2/tasks/1/members",
"owners": "/api/v2/tasks/1/owners",
"runs": "/api/v2/tasks/1/runs",
"self": "/api/v2/tasks/1"
},
"name": "string",
"offset": "string",
"org": "string",
"orgID": "string",
"ownerID": "string",
"status": "active",
"updatedAt": "2019-08-24T14:15:22Z"
}

List labels for a task

Retrieves a list of all labels for a task.

Labels may be used for grouping and filtering tasks.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to retrieve labels for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a task

Adds a label to a task.

Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to label.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

An object that contains a labelID to add to the task.

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a task

Deletes a label from a task.

Authorizations:

TokenAuthentication

path Parameters

labelID required	string The ID of the label to delete.
taskID required	string The ID of the task to delete the label from.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
404
500
default

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

Retrieve all logs for a task

Retrieves a list of all logs for a task.

When an InfluxDB task runs, a “run” record is created in the task’s history. Logs associated with each run provide relevant log messages, timestamps, and the exit status of the run attempt.

Use this endpoint to retrieve only the log events for a task, without additional task metadata.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The task ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

Example

{"events": [{"message": "Started task from script: \"option task = {name: \\\"test task\\\", every: 3d, offset: 0s}\"",
"runID": "09a946fc3167d000",
"time": "2022-07-13T07:06:54.198167Z"
},
{"message": "Completed(failed)",
"runID": "09a946fc3167d000",
"time": "2022-07-13T07:07:13.104037Z"
},
{"message": "error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a \"yield\" or invoking streaming functions directly, without performing an assignment",
"runID": "09a946fc3167d000",
"time": "2022-07-13T08:24:37.115323Z"
}
]
}

List all task members Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Lists all users that have the member role for the specified task.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The task ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}
]
}

Add a member to a task Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Adds a user to members of a task and returns the member.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The task ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A user to add as a member of the task.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}

Remove a member from a task Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Removes a member from a task.

Authorizations:

TokenAuthentication

path Parameters

taskID required	string The task ID.
userID required	string The ID of the member to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all owners of a task Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Retrieves all users that have owner permission for a task.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to retrieve owners for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
422
500
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}
]
}

Add an owner for a task Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Assigns a task owner role to a user.

Use this endpoint to create a resource owner for the task. A resource owner is a user with role: owner for a specific resource.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The task ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

A user to add as an owner of the task.

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
401
422
500
default

Content type

application/json

{"id": "0772396d1f411000",
"links": {"logs": "/api/v2/users/0772396d1f411000/logs",
"self": "/api/v2/users/0772396d1f411000"
},
"name": "USER_NAME",
"role": "owner",
"status": "active"
}

Remove an owner from a task Deprecated

Deprecated: Tasks don't use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Authorizations:

TokenAuthentication

path Parameters

taskID required	string The task ID.
userID required	string The ID of the owner to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List runs for a task

Retrieves a list of runs for a task.

To limit which task runs are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all task runs up to the default limit.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

The ID of the task to get runs for. Only returns runs for this task.

query Parameters

after	string A task run ID. Only returns runs created after this run.
afterTime	string <date-time> A timestamp (RFC3339 date/time format). Only returns runs scheduled after this time.
beforeTime	string <date-time> A timestamp (RFC3339 date/time format). Only returns runs scheduled before this time.
limit	integer [ 1 .. 500 ] Default: 100 Limits the number of task runs returned. Default is `100`.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
500
default

Content type

application/json

{"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
},
"runs": [{"finishedAt": "2006-01-02T15:04:05.999999999Z07:00",
"flux": "string",
"id": "string",
"links": {"retry": "/api/v2/tasks/1/runs/1/retry",
"self": "/api/v2/tasks/1/runs/1",
"task": "/api/v2/tasks/1"
},
"log": [{"message": "Halt and catch fire",
"runID": "string",
"time": "2006-01-02T15:04:05.999999999Z07:00"
}
],
"requestedAt": "2006-01-02T15:04:05.999999999Z07:00",
"scheduledFor": "2019-08-24T14:15:22Z",
"startedAt": "2006-01-02T15:04:05.999999999Z07:00",
"status": "scheduled",
"taskID": "string"
}
]
}

Start a task run, overriding the schedule

Schedules a task run to start immediately, ignoring scheduled runs.

Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks.

To retry a previous run (and avoid creating a new run), use the POST /api/v2/tasks/{taskID}/runs/{runID}/retry endpoint.

Authorizations:

TokenAuthentication

path Parameters

taskID

required

string

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

scheduledFor

string or null <date-time>

The time RFC3339 date/time format used for the run's now option. Default is the server now time.

Responses

Request samples

Payload

Content type

application/json

{"scheduledFor": "2019-08-24T14:15:22Z"
}

Response samples

201
401
500
default

Content type

application/json

{"finishedAt": "2006-01-02T15:04:05.999999999Z07:00",
"flux": "string",
"id": "string",
"links": {"retry": "/api/v2/tasks/1/runs/1/retry",
"self": "/api/v2/tasks/1/runs/1",
"task": "/api/v2/tasks/1"
},
"log": [{"message": "Halt and catch fire",
"runID": "string",
"time": "2006-01-02T15:04:05.999999999Z07:00"
}
],
"requestedAt": "2006-01-02T15:04:05.999999999Z07:00",
"scheduledFor": "2019-08-24T14:15:22Z",
"startedAt": "2006-01-02T15:04:05.999999999Z07:00",
"status": "scheduled",
"taskID": "string"
}

Cancel a running task

Cancels a running task.

Use this endpoint with InfluxDB OSS to cancel a running task.

InfluxDB Cloud

Doesn't support this operation.

Authorizations:

TokenAuthentication

path Parameters

runID required	string The ID of the task run to cancel.
taskID required	string The ID of the task to cancel.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"code": "invalid",
"message": "failed to decode request body: organization not found"
}

Retrieve a run for a task.

Retrieves a specific run for a task.

Use this endpoint to retrieve detail and logs for a specific task run.

Authorizations:

TokenAuthentication

path Parameters

runID required	string The ID of the run to retrieve.
taskID required	string The ID of the task to retrieve runs for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

{"finishedAt": "2022-07-18T14:46:07.308254Z",
"id": "09b070dadaa7d000",
"links": {"logs": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs",
"retry": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry",
"self": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000",
"task": "/api/v2/tasks/0996e56b2f378000"
},
"log": [{"message": "Started task from script: \"option task = {name: \\\"task1\\\", every: 30m} from(bucket: \\\"iot_center\\\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \\\"environment\\\")               |> aggregateWindow(every: 1h, fn: mean)\"",
"runID": "09b070dadaa7d000",
"time": "2022-07-18T14:46:07.101231Z"
},
{"message": "Completed(success)",
"runID": "09b070dadaa7d000",
"time": "2022-07-18T14:46:07.242859Z"
}
],
"requestedAt": "2022-07-18T14:46:06Z",
"scheduledFor": "2022-07-18T14:46:06Z",
"startedAt": "2022-07-18T14:46:07.16222Z",
"status": "success",
"taskID": "0996e56b2f378000"
}

Retrieve all logs for a run

Retrieves all logs for a task run. A log is a list of run events with runID, time, and message properties.

Use this endpoint to help analyze task performance and troubleshoot failed task runs.

Authorizations:

TokenAuthentication

path Parameters

runID required	string The ID of the run to get logs for.
taskID required	string The ID of the task to get logs for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

Content type

application/json

Example

{"events": [{"message": "Started task from script: \"option task = {name: \\\"test task\\\", every: 3d, offset: 0s}\"",
"runID": "09a946fc3167d000",
"time": "2022-07-13T07:06:54.198167Z"
},
{"message": "Completed(failed)",
"runID": "09a946fc3167d000",
"time": "2022-07-13T07:07:13.104037Z"
},
{"message": "error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a \"yield\" or invoking streaming functions directly, without performing an assignment",
"runID": "09a946fc3167d000",
"time": "2022-07-13T08:24:37.115323Z"
}
]
}

Retry a task run

Queues a task run to retry and returns the scheduled run.

To manually start a new task run, use the POST /api/v2/tasks/{taskID}/runs endpoint.

Limitations

The task must be active (status: "active").

Authorizations:

TokenAuthentication

path Parameters

runID required	string A task run ID. Specifies the task run to retry. To find a task run ID, use the `GET /api/v2/tasks/{taskID}/runs` endpoint to list task runs.
taskID required	string A task ID. Specifies the task to retry.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json; charset=utf-8

object

Responses

Request samples

Payload

Content type

application/json; charset=utf-8

{ }

Response samples

Content type

application/json

{"id": "09d60ffe08738000",
"links": {"logs": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs",
"retry": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry",
"self": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000",
"task": "/api/v2/tasks/09a776832f381000"
},
"requestedAt": "2022-08-16T20:05:11.84145Z",
"scheduledFor": "2022-08-15T00:00:00Z",
"status": "scheduled",
"taskID": "09a776832f381000"
}

Telegraf Plugins

List all Telegraf plugins

Authorizations:

TokenAuthentication

query Parameters

type	string The type of plugin desired.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"os": "string",
"plugins": [{"config": "string",
"description": "string",
"name": "string",
"type": "string"
}
],
"version": "string"
}

Telegrafs

List all Telegraf configurations

Authorizations:

TokenAuthentication

query Parameters

orgID

string

The organization ID the Telegraf config belongs to.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"configurations": [{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/telegrafs/1/labels",
"members": "/api/v2/telegrafs/1/members",
"owners": "/api/v2/telegrafs/1/owners",
"self": "/api/v2/telegrafs/1"
}
}
]
}

Create a Telegraf configuration

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Telegraf configuration to create

config	string
description	string
	object
name	string
orgID	string
	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"plugins": [{"alias": "string",
"config": "string",
"description": "string",
"name": "string",
"type": "string"
}
]
}

Response samples

201
default

Content type

application/json

{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/telegrafs/1/labels",
"members": "/api/v2/telegrafs/1/members",
"owners": "/api/v2/telegrafs/1/owners",
"self": "/api/v2/telegrafs/1"
}
}

Delete a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf configuration ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf configuration ID.

header Parameters

Accept	string Default: application/toml Enum: "application/toml" "application/json" "application/octet-stream"
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Responses

Response samples

200
default

Content type

{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/telegrafs/1/labels",
"members": "/api/v2/telegrafs/1/members",
"owners": "/api/v2/telegrafs/1/owners",
"self": "/api/v2/telegrafs/1"
}
}

Update a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Telegraf configuration update to apply

config	string
description	string
	object
name	string
orgID	string
	Array of objects

Responses

Request samples

Payload

Content type

application/json

{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"plugins": [{"alias": "string",
"config": "string",
"description": "string",
"name": "string",
"type": "string"
}
]
}

Response samples

200
default

Content type

application/json

{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/telegrafs/1/labels",
"members": "/api/v2/telegrafs/1/members",
"owners": "/api/v2/telegrafs/1/owners",
"self": "/api/v2/telegrafs/1"
}
}

List all labels for a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

labelID required	string The label ID.
telegrafID required	string The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all users with member privileges for a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}
]
}

Add a member to a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf config ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as member

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "member"
}

Remove a member from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID required	string The Telegraf config ID.
userID required	string The ID of the member to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

List all owners of a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf configuration ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}
]
}

Add an owner to a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters

telegrafID

required

string

The Telegraf configuration ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as owner

id required	string The ID of the user to add to the resource.
name	string The name of the user to add to the resource.

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string"
}

Response samples

201
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active",
"role": "owner"
}

Remove an owner from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters

telegrafID required	string The Telegraf config ID.
userID required	string The ID of the owner to remove.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Templates

Export and apply InfluxDB templates. Manage stacks of templated InfluxDB resources.

InfluxDB templates are prepackaged configurations for everything from dashboards and Telegraf to notifications and alerts. Use InfluxDB templates to quickly configure a fresh instance of InfluxDB, back up your dashboard configuration, or share your configuration with the InfluxData community.

Use the /api/v2/templates endpoints to export templates and apply templates.

InfluxDB stacks are stateful InfluxDB templates that let you add, update, and remove installed template resources over time, avoid duplicating resources when applying the same or similar templates more than once, and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.

Use the /api/v2/stacks endpoints to manage installed template resources.

List installed stacks

Lists installed InfluxDB stacks.

To limit stacks in the response, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all installed stacks for the organization.

View InfluxDB stacks.

Authorizations:

TokenAuthentication

query Parameters

name	string Examples: name=project-stack-0 - Find stacks with the event name A stack name. Finds stack `events` with this name and returns the stacks. Repeatable. To filter for more than one stack name, repeat this parameter with each name--for example: `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1`
orgID required	string An organization ID. Only returns stacks owned by the specified organization. InfluxDB Cloud Doesn't require this parameter; InfluxDB only returns resources allowed by the API token.
stackID	string Examples: stackID=09bd87cd33be3000 - Find a stack with the ID A stack ID. Only returns the specified stack. Repeatable. To filter for more than one stack ID, repeat this parameter with each ID--for example: `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000`

Responses

Response samples

200
400
401
500
default

Content type

application/json

{"stacks": [{"createdAt": "2019-08-24T14:15:22Z",
"events": [{"description": "string",
"eventType": "string",
"name": "string",
"resources": [{"apiVersion": "string",
"associations": [{"kind": "Bucket",
"metaName": "string"
}
],
"kind": "Bucket",
"links": {"self": "string"
},
"resourceID": "string",
"templateMetaName": "string"
}
],
"sources": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z",
"urls": ["string"
]
}
],
"id": "string",
"orgID": "string"
}
]
}

Create a stack

Creates or initializes a stack.

Use this endpoint to manually initialize a new stack with the following optional information:

Stack name
Stack description
URLs for template manifest files

To automatically create a stack when applying templates, use the /api/v2/templates/apply endpoint.

Required permissions

write permission for the organization

Authorizations:

TokenAuthentication

Request Body schema: application/json

The stack to create.

description	string
name	string
orgID	string
urls	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"description": "string",
"name": "string",
"orgID": "string",
"urls": ["string"
]
}

Response samples

201
401
422
500
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"events": [{"description": "string",
"eventType": "string",
"name": "string",
"resources": [{"apiVersion": "string",
"associations": [{"kind": "Bucket",
"metaName": "string"
}
],
"kind": "Bucket",
"links": {"self": "string"
},
"resourceID": "string",
"templateMetaName": "string"
}
],
"sources": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z",
"urls": ["string"
]
}
],
"id": "string",
"orgID": "string"
}

Delete a stack and associated resources

Authorizations:

TokenAuthentication

path Parameters

stack_id

required

string

The identifier of the stack.

query Parameters

orgID

required

string

The identifier of the organization.

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a stack

Authorizations:

TokenAuthentication

path Parameters

stack_id

required

string

The identifier of the stack.

Responses

Response samples

200
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"events": [{"description": "string",
"eventType": "string",
"name": "string",
"resources": [{"apiVersion": "string",
"associations": [{"kind": "Bucket",
"metaName": "string"
}
],
"kind": "Bucket",
"links": {"self": "string"
},
"resourceID": "string",
"templateMetaName": "string"
}
],
"sources": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z",
"urls": ["string"
]
}
],
"id": "string",
"orgID": "string"
}

Update a stack

Authorizations:

TokenAuthentication

path Parameters

stack_id

required

string

The identifier of the stack.

Request Body schema: application/json

The stack to update.

	Array of objects
description	string or null
name	string or null
templateURLs	Array of strings or null

Responses

Request samples

Payload

Content type

application/json

{"additionalResources": [{"kind": "string",
"resourceID": "string",
"templateMetaName": "string"
}
],
"description": "string",
"name": "string",
"templateURLs": ["string"
]
}

Response samples

200
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"events": [{"description": "string",
"eventType": "string",
"name": "string",
"resources": [{"apiVersion": "string",
"associations": [{"kind": "Bucket",
"metaName": "string"
}
],
"kind": "Bucket",
"links": {"self": "string"
},
"resourceID": "string",
"templateMetaName": "string"
}
],
"sources": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z",
"urls": ["string"
]
}
],
"id": "string",
"orgID": "string"
}

Uninstall a stack

Authorizations:

TokenAuthentication

path Parameters

stack_id

required

string

The identifier of the stack.

Responses

Response samples

200
default

Content type

application/json

{"createdAt": "2019-08-24T14:15:22Z",
"events": [{"description": "string",
"eventType": "string",
"name": "string",
"resources": [{"apiVersion": "string",
"associations": [{"kind": "Bucket",
"metaName": "string"
}
],
"kind": "Bucket",
"links": {"self": "string"
},
"resourceID": "string",
"templateMetaName": "string"
}
],
"sources": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z",
"urls": ["string"
]
}
],
"id": "string",
"orgID": "string"
}

Apply or dry-run a template

Applies a template to create or update a stack of InfluxDB resources. The response contains the diff of changes and the stack ID.

Use this endpoint to install an InfluxDB template to an organization. Provide template URLs or template objects in your request. To customize which template resources are installed, use the actions parameter.

By default, when you apply a template, InfluxDB installs the template to create and update stack resources and then generates a diff of the changes. If you pass dryRun: true in the request body, InfluxDB validates the template and generates the resource diff, but doesn’t make any changes to your instance.

Custom values for templates

Some templates may contain environment references for custom metadata. To provide custom values for environment references, pass the envRefs property in the request body. For more information and examples, see how to define environment references.
Some templates may contain queries that use secrets. To provide custom secret values, pass the secrets property in the request body. Don't expose secret values in templates. For more information, see how to pass secrets when installing a template.

Required permissions

write permissions for resource types in the template.

Rate limits (with InfluxDB Cloud)

Adjustable service quotas apply. For more information, see limits and adjustable quotas.

Authorizations:

TokenAuthentication

Request Body schema:
application/json
application/json
application/x-jsonnet
text/yml

Parameters for applying templates.

	Array of objects or objects A list of `action` objects. Actions let you customize how InfluxDB applies templates in the request. You can use the following actions to prevent creating or updating resources: A `skipKind` action skips template resources of a specified `kind`. A `skipResource` action skips template resources with a specified `metadata.name` and `kind`.
dryRun	boolean Only applies a dry run of the templates passed in the request. Validates the template and generates a resource diff and summary. Doesn't install templates or make changes to the InfluxDB instance.
	object An object with key-value pairs that map to environment references in templates. Environment references in templates are `envRef` objects with an `envRef.key` property. To substitute a custom environment reference value when applying templates, pass `envRefs` with the `envRef.key` and the value. When you apply a template, InfluxDB replaces `envRef` objects in the template with the values that you provide in the `envRefs` parameter. For more examples, see how to define environment references. The following template fields may use environment references: `metadata.name` `spec.endpointName` `spec.associations.name` For more information about including environment references in template fields, see how to include user-definable resource names.
orgID	string Organization ID. InfluxDB applies templates to this organization. The organization owns all resources created by the template. To find your organization, see how to view organizations.
	Array of objects A list of URLs for template files. To apply a template manifest file located at a URL, pass `remotes` with an array that contains the URL.
	object An object with key-value pairs that map to secrets in queries. Queries may reference secrets stored in InfluxDB--for example, the following Flux script retrieves `POSTGRES_USERNAME` and `POSTGRES_PASSWORD` secrets and then uses them to connect to a PostgreSQL database: `import "sql" import "influxdata/influxdb/secrets" username = secrets.get(key: "POSTGRES_USERNAME") password = secrets.get(key: "POSTGRES_PASSWORD") sql.from( driverName: "postgres", dataSourceName: "postgresql://${username}:${password}@localhost:5432", query: "SELECT * FROM example_table", )` To define secret values in your `/api/v2/templates/apply` request, pass the `secrets` parameter with key-value pairs--for example: `{ ... "secrets": { "POSTGRES_USERNAME": "pguser", "POSTGRES_PASSWORD": "foo" } ... }` InfluxDB stores the key-value pairs as secrets that you can access with `secrets.get()`. Once stored, you can't view secret values in InfluxDB. Related guides How to pass secrets when installing a template
stackID	string ID of the stack to update. To apply templates to an existing stack in the organization, use the `stackID` parameter. If you apply templates without providing a stack ID, InfluxDB initializes a new stack with all new resources. To find a stack ID, use the InfluxDB `/api/v2/stacks` API endpoint to list stacks. Related guides Stacks View stacks
	object A template object to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Pass `template` to apply only one template object. If you use `template`, you can't use the `templates` parameter. If you want to apply multiple template objects, use `templates` instead.
	Array of objects A list of template objects to apply. A template object has a `contents` property with an array of InfluxDB resource configurations. Use the `templates` parameter to apply multiple template objects. If you use `templates`, you can't use the `template` parameter.

Responses

Request samples

Payload
cURL: Dry run with a remote template
cURL: Apply with secret values
cURL: Apply template objects with environment references

Content type

Example

{"actions": [{"action": "skipKind",
"properties": {"kind": "Bucket"
}
},
{"action": "skipKind",
"properties": {"kind": "Task"
}
}
],
"orgID": "INFLUX_ORG_ID",
"templates": [{"contents": [{"[object Object]": null
}
]
}
]
}

Response samples

200
201
422
500
default

Content type

application/json

{"diff": {"buckets": [{"id": "string",
"kind": "Bucket",
"new": {"description": "string",
"name": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
]
},
"old": {"description": "string",
"name": "string",
"retentionRules": [{"everySeconds": 86400,
"shardGroupDurationSeconds": 0,
"type": "expire"
}
]
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"checks": [{"id": "string",
"kind": "Bucket",
"new": {"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": [null
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"every": "string",
"level": "UNKNOWN",
"offset": "string",
"reportZero": true,
"staleTime": "string",
"statusMessageTemplate": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeSince": "string",
"type": "deadman"
},
"old": {"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": [null
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"every": "string",
"level": "UNKNOWN",
"offset": "string",
"reportZero": true,
"staleTime": "string",
"statusMessageTemplate": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeSince": "string",
"type": "deadman"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"dashboards": [{"id": "string",
"kind": "Bucket",
"new": {"charts": [{"height": 0,
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": null,
"bounds": [ ],
"label": null,
"prefix": null,
"scale": null,
"suffix": null
},
"y": {"base": null,
"bounds": [ ],
"label": null,
"prefix": null,
"scale": null,
"suffix": null
}
},
"colors": [{"hex": null,
"id": null,
"name": null,
"type": null,
"value": null
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": null,
"editMode": null,
"name": null,
"text": null
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
},
"width": 0,
"xPos": 0,
"yPos": 0
}
],
"description": "string",
"name": "string"
},
"old": {"charts": [{"height": 0,
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": null,
"bounds": [ ],
"label": null,
"prefix": null,
"scale": null,
"suffix": null
},
"y": {"base": null,
"bounds": [ ],
"label": null,
"prefix": null,
"scale": null,
"suffix": null
}
},
"colors": [{"hex": null,
"id": null,
"name": null,
"type": null,
"value": null
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": null,
"editMode": null,
"name": null,
"text": null
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
},
"width": 0,
"xPos": 0,
"yPos": 0
}
],
"description": "string",
"name": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"labelMappings": [{"labelID": "string",
"labelName": "string",
"labelTemplateMetaName": "string",
"resourceID": "string",
"resourceName": "string",
"resourceTemplateMetaName": "string",
"resourceType": "string",
"status": "string"
}
],
"labels": [{"id": "string",
"kind": "Bucket",
"new": {"color": "string",
"description": "string",
"name": "string"
},
"old": {"color": "string",
"description": "string",
"name": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"notificationEndpoints": [{"id": "string",
"kind": "Bucket",
"new": {"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "slack",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"token": "string",
"url": "string"
},
"old": {"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "slack",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"token": "string",
"url": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"notificationRules": [{"id": "string",
"kind": "Bucket",
"new": {"description": "string",
"endpointID": "string",
"endpointName": "string",
"endpointType": "string",
"every": "string",
"messageTemplate": "string",
"name": "string",
"offset": "string",
"status": "string",
"statusRules": [{"currentLevel": "string",
"previousLevel": "string"
}
],
"tagRules": [{"key": "string",
"operator": "string",
"value": "string"
}
]
},
"old": {"description": "string",
"endpointID": "string",
"endpointName": "string",
"endpointType": "string",
"every": "string",
"messageTemplate": "string",
"name": "string",
"offset": "string",
"status": "string",
"statusRules": [{"currentLevel": "string",
"previousLevel": "string"
}
],
"tagRules": [{"key": "string",
"operator": "string",
"value": "string"
}
]
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"tasks": [{"id": "string",
"kind": "Bucket",
"new": {"cron": "string",
"description": "string",
"every": "string",
"name": "string",
"offset": "string",
"query": "string",
"status": "string"
},
"old": {"cron": "string",
"description": "string",
"every": "string",
"name": "string",
"offset": "string",
"query": "string",
"status": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"telegrafConfigs": [{"id": "string",
"kind": "Bucket",
"new": {"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string"
},
"old": {"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
],
"variables": [{"id": "string",
"kind": "Bucket",
"new": {"args": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"description": "string",
"name": "string"
},
"old": {"args": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"description": "string",
"name": "string"
},
"stateStatus": "string",
"templateMetaName": "string"
}
]
},
"errors": [{"fields": ["string"
],
"indexes": [0
],
"kind": "Bucket",
"reason": "string"
}
],
"sources": ["string"
],
"stackID": "string",
"summary": {"buckets": [{"description": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"name": "string",
"orgID": "string",
"retentionPeriod": 0,
"templateMetaName": "string"
}
],
"checks": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"lastRunError": "string",
"lastRunStatus": "failed",
"latestCompleted": "2019-08-24T14:15:22Z",
"links": {"labels": "/api/v2/checks/1/labels",
"members": "/api/v2/checks/1/members",
"owners": "/api/v2/checks/1/owners",
"query": "/api/v2/checks/1/query",
"self": "/api/v2/checks/1"
},
"name": "string",
"orgID": "string",
"ownerID": "string",
"query": {"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
},
"status": "active",
"taskID": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"every": "string",
"level": "UNKNOWN",
"offset": "string",
"reportZero": true,
"staleTime": "string",
"statusMessageTemplate": "string",
"tags": [{"key": "string",
"value": "string"
}
],
"timeSince": "string",
"type": "deadman",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"templateMetaName": "string"
}
],
"dashboards": [{"charts": [{"height": 0,
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": [null
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": [null
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": { },
"buckets": [ ],
"functions": [ ],
"tags": [ ]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
},
"width": 0,
"xPos": 0,
"yPos": 0
}
],
"description": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"name": "string",
"orgID": "string",
"templateMetaName": "string"
}
],
"labelMappings": [{"labelID": "string",
"labelName": "string",
"labelTemplateMetaName": "string",
"resourceID": "string",
"resourceName": "string",
"resourceTemplateMetaName": "string",
"resourceType": "string",
"status": "string"
}
],
"labels": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"missingEnvRefs": ["string"
],
"missingSecrets": ["string"
],
"notificationEndpoints": [{"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "/api/v2/notificationEndpoints/1/labels",
"members": "/api/v2/notificationEndpoints/1/members",
"owners": "/api/v2/notificationEndpoints/1/owners",
"self": "/api/v2/notificationEndpoints/1"
},
"name": "string",
"orgID": "string",
"status": "active",
"type": "slack",
"updatedAt": "2019-08-24T14:15:22Z",
"userID": "string",
"token": "string",
"url": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"templateMetaName": "string"
}
],
"notificationRules": [{"description": "string",
"endpointID": "string",
"endpointTemplateMetaName": "string",
"endpointType": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"every": "string",
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"messageTemplate": "string",
"name": "string",
"offset": "string",
"status": "string",
"statusRules": [{"currentLevel": "string",
"previousLevel": "string"
}
],
"tagRules": [{"key": "string",
"operator": "string",
"value": "string"
}
],
"templateMetaName": "string"
}
],
"tasks": [{"cron": "string",
"description": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"every": "string",
"id": "string",
"kind": "Bucket",
"name": "string",
"offset": "string",
"query": "string",
"status": "string",
"templateMetaName": "string"
}
],
"telegrafConfigs": [{"config": "string",
"description": "string",
"metadata": {"buckets": ["string"
]
},
"name": "string",
"orgID": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"templateMetaName": "string"
}
],
"variables": [{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"description": "string",
"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"labelAssociations": [{"envReferences": [{"defaultValue": "string",
"envRefKey": "string",
"resourceField": "string",
"value": "string"
}
],
"id": "string",
"kind": "Bucket",
"name": "string",
"orgID": "string",
"properties": {"color": "string",
"description": "string"
},
"templateMetaName": "string"
}
],
"name": "string",
"orgID": "string",
"templateMetaName": "string"
}
]
}
}

Export a new template

Authorizations:

TokenAuthentication

Request Body schema: application/json

Export resources as an InfluxDB template.

One of

	Array of objects
	Array of objects
stackID	string

Responses

Request samples

Payload

Content type

application/json

Example

{"orgIDs": [{"orgID": "string",
"resourceFilters": {"byLabel": ["string"
],
"byResourceKind": ["Bucket"
]
}
}
],
"resources": [{"id": "string",
"kind": "Bucket",
"name": "string"
}
],
"stackID": "string"
}

Response samples

200
default

Content type

[{"apiVersion": "influxdata.com/v2alpha1",
"kind": "Bucket",
"metadata": {"name": "string"
},
"spec": { }
}
]

Users

Manage users for your organization. Users are those with access to InfluxDB. To grant a user permission to access data, add them as a member of an organization and provide them with an API token.

User sessions with authorizations

Optionally, you can scope an authorization (and its API token) to a user. If a user signs in with username and password, creating a user session, the session carries the permissions granted by all the user's authorizations. To create a user session, use the POST /api/v2/signin endpoint.

Retrieve the currently authenticated user

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
500
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}

Update a password

Updates the password for the signed-in user.

This endpoint represents the third step in the following three-step process to let a user with a user session update their password:

Pass the user's Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
From the response in the first step, extract the session cookie (Set-Cookie) header.
Pass the following in a request to the PUT /api/v2/me/password endpoint:
- The Set-Cookie header from the second step
- The Authorization Basic header with the user's Basic authentication credentials
- {"password": "NEW_PASSWORD"} in the request body

InfluxDB Cloud

Doesn't let you manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update your password.

Signin
Signout
Users

Authorizations:

BasicAuthentication

cookie Parameters

influxdb-oss-session

required

string

Example: influxdb-oss-session=influxdb-oss-session=19aaaZZZGOvP2GGryXVT2qYftlFKu3bIopurM6AGFow1yF1abhtOlbHfsc-d8gozZFC_6WxmlQIAwLMW5xs523w==

The user session cookie for the user signed in with Basic authentication credentials.

Manage users

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password.

password

required

string

Responses

Request samples

Payload

Content type

application/json

{"password": "string"
}

Response samples

401
default

Content type

application/json

{"code": "unauthorized",
"message": "unauthorized access"
}

List users

Lists users. Default limit is 20.

To limit which users are returned, pass query parameters in your request.

Required permissions for InfluxDB OSS

Action	Permission required	Restriction
List all users	Operator token
List a specific user	`read-users` or `read-user USER_ID`

USER_ID is the ID of the user that you want to retrieve.

View users.

Authorizations:

TokenAuthentication

query Parameters

after	string A resource ID to seek from. Returns records created after the specified record; results don't include the specified record. Use `after` instead of the `offset` parameter. For more information about pagination parameters, see Pagination.
id	string A user ID. Only lists the specified user.
limit	integer [ 1 .. 100 ] Default: 20 Limits the number of records returned. Default is `20`.
name	string A user name. Only lists the specified user.
offset	integer >= 0 The offset for pagination. The number of records to skip. For more information about pagination parameters, see Pagination.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
401
422
500
default

Content type

application/json

{"links": {"self": "http://example.com"
},
"users": [{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}
]
}

Create a user

Creates a user that can access InfluxDB. Returns the user.

Use this endpoint to create a user that can sign in to start a user session through one of the following interfaces:

InfluxDB UI
/api/v2/signin InfluxDB API endpoint
InfluxDB CLI

This endpoint represents the first two steps in a four-step process to allow a user to authenticate with a username and password, and then access data in an organization:

Create a user: send a POST request to POST /api/v2/users. The name property is required.
Extract the user ID (id property) value from the API response for step 1.
Create an authorization (and API token) for the user: send a POST request to POST /api/v2/authorizations, passing the user ID (id) from step 2.
Create a password for the user: send a POST request to POST /api/v2/users/USER_ID/password, passing the user ID from step 2.

Required permissions

Action	Permission required	Restriction
Create a user	Operator token

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The user to create.

name required	string The user name.
status	string Default: "active" Enum: "active" "inactive" If `inactive`, the user is inactive. Default is `active`.

Responses

Request samples

Payload
cURL: create a user and set a password

Content type

application/json

{"name": "string",
"status": "active"
}

Response samples

201
401
422
500
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}

Delete a user

Deletes a user.

Required permissions

Action	Permission required
Delete a user	`write-users` or `write-user USER_ID`

USER_ID is the ID of the user that you want to delete.

Manage users

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

A user ID. Specifies the user to delete.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

400
401
500
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a user

Retrieves a user.

Manage users

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

A user ID. Retrieves the specified user.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}

Update a user

Updates a user and returns the user.

Required permissions

Action	Permission required
Update a user	`write-users` or `write-user USER_ID`

USER_ID is the ID of the user that you want to update.

Manage users

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

A user ID. Specifies the user to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

In the request body, provide the user properties to update.

name required	string The user name.
status	string Default: "active" Enum: "active" "inactive" If `inactive`, the user is inactive. Default is `active`.

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"status": "active"
}

Response samples

Content type

application/json

{"id": "string",
"links": {"self": "/api/v2/users/1"
},
"name": "string",
"status": "active"
}

Update a password

Updates a user password.

InfluxDB Cloud

Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Authorizations:

TokenAuthentication

path Parameters

userID

required

string

The ID of the user to set the password for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password

required

string

Responses

Request samples

Payload
cURL: use HTTP POST to update the user password

Content type

application/json

{"password": "string"
}

Response samples

400
default

Content type

application/json

{"code": "invalid",
"message": "passwords cannot be changed through the InfluxDB Cloud API"
}

Update a password

Updates a user password.

Use this endpoint to let a user authenticate with Basic authentication credentials and set a new password.

InfluxDB Cloud

Doesn't allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.

Authorizations:

BasicAuthentication

path Parameters

userID

required

string

The ID of the user to set the password for.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password

required

string

Responses

Request samples

Payload
cURL: use Basic auth to update the user password

Content type

application/json

{"password": "string"
}

Response samples

400
default

Content type

application/json

{"code": "invalid",
"message": "passwords cannot be changed through the InfluxDB Cloud API"
}

Variables

List all variables

Authorizations:

TokenAuthentication

query Parameters

org	string The name of the organization.
orgID	string The organization ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
400
default

Content type

application/json

{"variables": [{"arguments": {"type": "constant",
"values": ["howdy",
"hello",
"hi",
"yo",
"oy"
]
},
"id": "1221432",
"name": ":ok:",
"selected": ["hello"
]
},
{"arguments": {"type": "map",
"values": {"a": "fdjaklfdjkldsfjlkjdsa",
"b": "dfaksjfkljekfajekdljfas",
"c": "fdjksajfdkfeawfeea"
}
},
"id": "1221432",
"name": ":ok:",
"selected": ["c"
]
},
{"arguments": {"language": "flux",
"query": "from(bucket: \"foo\") |> showMeasurements()",
"type": "query"
},
"id": "1221432",
"name": ":ok:",
"selected": ["host"
]
}
]
}

Create a variable

Authorizations:

TokenAuthentication

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable to create

required	QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt	string <date-time>
description	string
	Array of objects (Labels)
name required	string
orgID required	string
selected	Array of strings
updatedAt	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

201
default

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "http://example.com",
"org": "http://example.com",
"self": "http://example.com"
},
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Delete a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Retrieve a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "http://example.com",
"org": "http://example.com",
"self": "http://example.com"
},
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Update a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable update to apply

required	QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt	string <date-time>
description	string
	Array of objects (Labels)
name required	string
orgID required	string
selected	Array of strings
updatedAt	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

200
default

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "http://example.com",
"org": "http://example.com",
"self": "http://example.com"
},
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Replace a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable to replace

required	QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt	string <date-time>
description	string
	Array of objects (Labels)
name required	string
orgID required	string
selected	Array of strings
updatedAt	string <date-time>

Responses

Request samples

Payload

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"labels": [{"name": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

200
default

Content type

application/json

{"arguments": {"type": "query",
"values": {"language": "string",
"query": "string"
}
},
"createdAt": "2019-08-24T14:15:22Z",
"description": "string",
"id": "string",
"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"labels": "http://example.com",
"org": "http://example.com",
"self": "http://example.com"
},
"name": "string",
"orgID": "string",
"selected": ["string"
],
"updatedAt": "2019-08-24T14:15:22Z"
}

List all labels for a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
default

Content type

application/json

{"labels": [{"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
}
],
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Add a label to a variable

Authorizations:

TokenAuthentication

path Parameters

variableID

required

string

The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID

required

string

A label ID. Specifies the label to attach.

Responses

Request samples

Payload

Content type

application/json

{"labelID": "string"
}

Response samples

201
default

Content type

application/json

{"label": {"id": "string",
"name": "string",
"orgID": "string",
"properties": {"color": "ffb3b3",
"description": "this is a description"
}
},
"links": {"next": "http://example.com",
"prev": "http://example.com",
"self": "http://example.com"
}
}

Delete a label from a variable

Authorizations:

TokenAuthentication

path Parameters

labelID required	string The label ID to delete.
variableID required	string The variable ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

404
default

Content type

application/json

{"code": "internal error",
"err": "string",
"message": "string",
"op": "string"
}

Views

Retrieve the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The cell ID.
dashboardID required	string The dashboard ID.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters

cellID required	string The ID of the cell to update.
dashboardID required	string The ID of the dashboard to update.

header Parameters

Zap-Trace-Span

string

Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

name

required

string

required

LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Response samples

200
404
default

Content type

application/json

{"id": "string",
"links": {"self": "string"
},
"name": "string",
"properties": {"adaptiveZoomHide": true,
"axes": {"x": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
},
"y": {"base": "",
"bounds": ["string"
],
"label": "string",
"prefix": "string",
"scale": "log",
"suffix": "string"
}
},
"colors": [{"hex": "strings",
"id": "string",
"name": "string",
"type": "min",
"value": 0
}
],
"decimalPlaces": {"digits": 0,
"isEnforced": true
},
"generateXAxisTicks": ["string"
],
"generateYAxisTicks": ["string"
],
"hoverDimension": "auto",
"legendColorizeRows": true,
"legendHide": true,
"legendOpacity": 0,
"legendOrientationThreshold": 0,
"note": "string",
"position": "overlaid",
"prefix": "string",
"queries": [{"builderConfig": {"aggregateWindow": {"fillValues": true,
"period": "string"
},
"buckets": ["string"
],
"functions": [{"name": "string"
}
],
"tags": [{"aggregateFunctionType": "filter",
"key": "string",
"values": ["string"
]
}
]
},
"editMode": "builder",
"name": "string",
"text": "string"
}
],
"shadeBelow": true,
"shape": "chronograf-v2",
"showNoteWhenEmpty": true,
"staticLegend": {"colorizeRows": true,
"heightRatio": 0,
"opacity": 0,
"orientationThreshold": 0,
"show": true,
"valueAxis": "string",
"widthRatio": 0
},
"suffix": "string",
"timeFormat": "string",
"type": "line-plus-single-stat",
"xColumn": "string",
"xTickStart": 0,
"xTickStep": 0,
"xTotalTicks": 0,
"yColumn": "string",
"yTickStart": 0,
"yTickStep": 0,
"yTotalTicks": 0
}
}

Write

Write time series data to buckets.

Write data

Writes data to a bucket.

Use this endpoint to send data in line protocol format to InfluxDB.

InfluxDB Cloud

Does the following when you send a write request:
1. Validates the request and queues the write.
2. If queued, responds with success (HTTP 2xx status code); error otherwise.
3. Handles the delete asynchronously and reaches eventual consistency.
To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

Validates the request and handles the write synchronously.
If all points were written successfully, responds with HTTP 2xx status code; otherwise, returns the first line that failed.

Required permissions

write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Authorizations:

TokenAuthentication

query Parameters

bucket required	string A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket.
org required	string An organization name or ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Writes data to the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. If you pass both `orgID` and `org`, they must both be valid. Writes data to the bucket in the specified organization.
orgID	string An organization ID. InfluxDB Cloud Doesn't use the `org` parameter or `orgID` parameter. Writes data to the bucket in the organization associated with the authorization (API token). InfluxDB OSS Requires either the `org` parameter or the `orgID` parameter. If you pass both `orgID` and `org`, they must both be valid. Writes data to the bucket in the specified organization.
precision	string (WritePrecision) Enum: "ms" "s" "us" "ns" The precision for unix timestamps in the line protocol batch.

header Parameters

Accept	string Default: application/json Value: "application/json" The content type that the client can understand. Writes only return a response body if they fail--for example, due to a formatting problem or quota limit. InfluxDB Cloud Returns only `application/json` for format and limit errors. Returns only `text/html` for some quota limit errors. InfluxDB OSS Returns only `application/json` for format and limit errors. Related guides Troubleshoot issues writing data
Content-Encoding	string Default: identity Enum: "gzip" "identity" The compression applied to the line protocol in the request payload. To send a gzip payload, pass `Content-Encoding: gzip` header.
Content-Length	integer The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the `max body` configuration option, the server responds with status code `413`.
Content-Type	string Default: text/plain; charset=utf-8 Enum: "text/plain" "text/plain; charset=utf-8" The format of the data in the request body. To send a line protocol payload, pass `Content-Type: text/plain; charset=utf-8`.
Zap-Trace-Span	string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context

Request Body schema: text/plain

In the request body, provide data in line protocol format.

To send compressed data, do the following:

Use gzip to compress the line protocol data.
In your request, send the compressed data and the Content-Encoding: gzip header.

Best practices for optimizing writes

string <byte>

Responses

Request samples

Payload

Content type

text/plain

airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000

Response samples

Content type

application/json

Example

{"code": "invalid",
"message": "partial write error (2 written): unable to parse 'air_sensor,service=S1,sensor=L1 temperature=\"90.5\",humidity=70.0 1632850122': schema: field type for field \"temperature\" not permitted by schema; got String but expected Float"
}

InfluxDB OSS API Service (2.7.0)

Quick start

Authentication

BasicAuthentication

Basic authentication scheme

Syntax

Examples

Encode credentials with cURL

Encode credentials with Flux

Encode credentials with JavaScript

TokenAuthentication

Syntax

Example

Use Token authentication with cURL

Related endpoints

Related guides

Supported operations

Headers

Pagination

Limitations

Response codes

Data I/O endpoints

Delete data

InfluxDB Cloud

InfluxDB OSS

Required permissions

Rate limits (with InfluxDB Cloud)

Related guides

Authorizations:

query Parameters

InfluxDB Cloud

InfluxDB OSS

InfluxDB Cloud

InfluxDB OSS

header Parameters

Request Body schema: application/json

Related guides

Responses

InfluxDB Cloud

InfluxDB OSS

InfluxDB OSS

Request samples

Response samples

Query data

Rate limits (with InfluxDB Cloud)

Related guides

Authorizations:

query Parameters

InfluxDB Cloud

InfluxDB OSS

InfluxDB Cloud

InfluxDB OSS

header Parameters

Request Body schema: application/jsonapplication/jsonapplication/vnd.flux

Responses

InfluxDB OSS

InfluxDB Cloud:

InfluxDB OSS:

Request samples

Response samples

List tasks

Related guide

Authorizations:

query Parameters

header Parameters

Responses

Request samples

Response samples

Create a task

Related guides

Authorizations:

header Parameters

Request Body schema: application/json

Responses

InfluxDB OSS

Request samples

Response samples

Retrieve a task

Authorizations:

path Parameters

Request Body schema:
application/json
application/json
application/vnd.flux