InfluxDB v2 Cloud Docs Submit API issue
Documentation Powered by ReDoc

InfluxDB Cloud API Service (2.x)

License: MIT

The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2.

The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with InfluxDB v2. Access the InfluxDB API using /api/v2/ and InfluxDB v1-compatible endpoints.

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:

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:

  • EMAIL_ADDRESS: InfluxDB Cloud username (the email address the user signed up with)
  • PASSWORD: InfluxDB Cloud API token
  • INFLUX_URL: your InfluxDB Cloud 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 "EMAIL_ADDRESS":"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('EMAIL_ADDRESS: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 TypeHTTP
HTTP Authorization Schemebasic

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:

Security Scheme TypeAPI 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
WriteWrites (POST) data to a bucket.
RunExecutes (POST) a query or script and returns the result.
ListRetrieves (GET) a list of zero or more resources.
CreateCreates (POST) a new resource and returns the resource.
UpdateModifies (PUT) an existing resource to reflect data in your request.
DeleteRemoves (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.

HeaderValue typeDescription
AcceptstringThe content type that the client can understand.
AuthorizationstringThe authorization scheme and credential.
Content-LengthintegerThe size of the entity-body, in bytes, sent to the database.
Content-TypestringThe format of the data in the request body.

Pagination

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

Query parameterValue typeDescription
limitintegerThe maximum number of records to return (after other parameters are applied).
offsetintegerThe number of records to skip (before limit, after other parameters are applied).
afterstring (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 StatusDescription
200Success
204No contentFor a POST request, 204 indicates that InfluxDB accepted the request and request data is valid. Asynchronous operations, such as write, might not have completed yet.
400Bad requestInfluxDB can't parse the request due to an incorrect parameter or bad syntax. For writes, the error may indicate one of the following problems:
  • 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.
401UnauthorizedMay 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
404Not foundRequested resource was not found. message in the response body provides details about the requested resource.
405Method not allowedThe API path doesn't support the HTTP method used in the request--for example, you send a POST request to an endpoint that only allows GET.
413Request entity too largeRequest payload exceeds the size limit.
422Unprocessable entityRequest data is invalid. code and message in the response body provide details about the problem.
429Too many requestsAPI token is temporarily over the request quota. The Retry-After header describes when to try the request again.
500Internal server error
503Service unavailableServer 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.

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.

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

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

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.

object

Key-value pairs passed as parameters during query execution.

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

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

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

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

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

Limitations

  • If you use params, you can't use extern.
query
required
string

The query script to execute.

type
string
Value: "flux"

The type of query. Must be "flux".

Responses

Request samples

Content type
application/json
application/json
application/vnd.flux
{
  • "dialect": {
    },
  • "extern": {
    },
  • "now": "2019-08-24T14:15:22Z",
  • "params": { },
  • "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 scripts

Lists scripts.

Authorizations:
TokenAuthentication
query Parameters
limit
integer [ 0 .. 500 ]
Default: 100

The maximum number of scripts to return. Default is 100.

name
string

The script name. Lists scripts 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.

Responses

Request samples

curl --request GET "INFLUX_URL/api/v2/scripts?limit=100&offset=0" \
  --header "Authorization: Token INFLUX_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "scripts": [
    ]
}

Retrieve a script

Retrieves a script.

Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Retrieves the specified script.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2022-07-17T23:49:45.731237Z",
  • "description": "getLastPoint finds the last point in a bucket",
  • "id": "09afa3b220fe4000",
  • "language": "flux",
  • "name": "getLastPoint",
  • "orgID": "bea7ea952287f70d",
  • "script": "from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)",
  • "updatedAt": "2022-07-17T23:49:45.731237Z"
}

Invoke a script

Runs a script and returns the result. When the script runs, InfluxDB replaces params keys referenced in the script with params key-values passed in the request body--for example:

The following sample script contains a mybucket parameter :

"script": "from(bucket: params.mybucket)
            |> range(start: -7d)
            |> limit(n:1)"

The following example POST /api/v2/scripts/SCRIPT_ID/invoke request body passes a value for the mybucket parameter:

{
  "params": {
    "mybucket": "air_sensor"
  }
}
Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Runs the specified script.

Request Body schema: application/json
object

The script parameters. params contains key-value pairs that map values to the params.keys in a script. When you invoke a script with params, InfluxDB passes the values as invocation parameters to the script.

Responses

Request samples

Content type
application/json
{
  • "params": { }
}

Response samples

Content type
text/csv
,result,table,_start,_stop,_time,_value,_field,_measurement,host
,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2

List all 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.

Authorizations:
TokenAuthentication
query Parameters
after
string

A task ID. Only returns tasks created after the specified task.

limit
integer [ -1 .. 500 ]
Default: 100
Examples:
  • limit=-1 - Return all tasks, without pagination.
  • limit=50 - Return a maximum of 50 tasks.

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.

offset
integer >= 0
Default: 0

The number of records to skip.

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.

scriptID
string

A script ID. Only returns tasks that use the specified invokable script.

sortBy
string
Value: "name"

The sort field. Only name is supported. Specifies the field used to sort records in the list.

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 INFLUX_URL/api/v2/tasks/?limit=-1&type=basic \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token INFLUX_API_TOKEN'

Response samples

Content type
application/json
Example
Basic output
Basic output
System output

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": {
    },
  • "tasks": [
    ]
}

Create a task

Creates a task and returns the task.

Use this endpoint to create a scheduled task that runs a Flux script.

InfluxDB Cloud

  • You can use either flux or scriptID to provide the task script.

    • flux: a string of "raw" Flux that contains task options and the script--for example:

      {
  "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\
  from(bucket: \"telegraf\")
    |> range(start: -1h)
    |> filter(fn: (r) => (r._measurement == \"cpu\"))
    |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))
    |> filter(fn: (r) => (r.cpu == \"cpu-total\"))
    |> aggregateWindow(every: 1h, fn: max)
    |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")",
  "status": "active",
  "description": "This task downsamples CPU data every hour"
}

    • scriptID: the ID of an invokable script for the task to run. To pass task options when using scriptID, pass the options as properties in the request body--for example:

      {
  "name": "CPU Total 1 Hour New",
  "description": "This task downsamples CPU data every hour",
  "every": "1h",
  "scriptID": "SCRIPT_ID",
  "scriptParameters":
    {
      "rangeStart": "-1h",
      "bucket": "telegraf",
      "filterField": "cpu-total"
    }
  }

Limitations:

  • You can't use flux and scriptID for the same 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

cron
string

A Cron expression that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.

description
string

The description of the task.

every
string

The interval (duration literal)) at which the task runs. every also determines when the task first runs, depending on the specified time.

flux
string

The Flux script that the task runs.

Limitations

  • If you use the flux property, you can't use the scriptID and scriptParameters properties.
name
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

The name of the organization that owns the task.

orgID
string

The ID of the organization that owns the task.

scriptID
string

The ID of the script that the task runs.

Limitations

  • If you use the scriptID property, you can't use the flux property.
scriptParameters
object

The parameter key-value pairs passed to the script (referenced by scriptID) during the task run.

Limitations

  • scriptParameters requires scriptID.
  • If you use the scriptID and scriptParameters properties, you can't use the flux property.
status
string (TaskStatusType)
Enum: "active" "inactive"

inactive cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Content type
application/json
{
  • "cron": "string",
  • "description": "string",
  • "every": "string",
  • "flux": "string",
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "status": "active",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Retrieve a task

Retrieves a task.

Authorizations:
TokenAuthentication
path Parameters
taskID
required
string

A task ID. Specifies 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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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

Content type
application/json
{
  • "scheduledFor": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "finishedAt": "2006-01-02T15:04:05.999999999Z07:00",
  • "flux": "string",
  • "id": "string",
  • "links": {
    },
  • "log": [
    ],
  • "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.
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:

  1. Use gzip to compress the line protocol data.
  2. In your request, send the compressed data and the Content-Encoding: gzip header.
string <byte>

Responses

Request samples

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
(Cloud) field type conflict thrown by an explicit bucket schema
(Cloud) field type conflict thrown by an explicit bucket schema
(OSS) organization not found
{
  • "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
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

Content type
application/json
{
  • "authorizations": [
    ],
  • "links": {}
}

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

Content type
application/json
Example
An authorization for a resource type
An authorization for a resource type
An authorization for a resource
An authorization scoped to a user

Creates an authorization.

{
  • "description": "iot_users read buckets",
  • "orgID": "INFLUX_ORG_ID",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

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
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": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

Content type
application/json
{
  • "description": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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.
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": {
    },
  • "orgs": [
    ]
}

Retrieve an organization

Retrieves an organization.

Use this endpoint to retrieve information for a specific organization.

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

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "defaultStorageType": "tsm",
  • "description": "string",
  • "id": "string",
  • "links": {
    },
  • "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

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": {
    },
  • "users": [
    ]
}

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

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.

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

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized access"
}

List all owners of an organization

Lists all owners of an organization.

InfluxDB Cloud

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

Content type
application/json
{
  • "links": {
    },
  • "users": [
    ]
}

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

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

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

Content type
application/json
{
  • "secrets": [
    ],
  • "links": {
    }
}

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

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

Content type
application/json
{
  • "secrets": [
    ]
}

Response samples

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.
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 --request POST http://localhost:8086/api/v2/signin \
     --user "USERNAME:PASSWORD"

Response samples

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:

  1. 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.
  2. Send a request to the GET /api/v2/me endpoint, passing the stored session cookie from step 1 to retrieve user information.
  3. 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.

Authorizations:
TokenAuthentication
header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

# 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

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "message": "string",
  • "op": "string"
}

List users

Lists users.

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

InfluxDB Cloud

  • InfluxDB Cloud doesn't allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions for InfluxDB Cloud

ActionPermission requiredRestriction
List all usersOperator tokenInfluxData internal use only
List a specific userread-users or read-user USER_ID

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

Authorizations:
TokenAuthentication
query Parameters
id
string

A user id. Only lists the specified user.

name
string

A user name. Only lists 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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "password": "string"
}

Response samples

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

Content type
application/json
{
  • "password": "string"
}

Response samples

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

Content type
application/json
{}

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.

Authorizations:
TokenAuthentication

Responses

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

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 the following for managing your tokens:

  • Create a generic user to create and manage tokens for writing data.
  • Store your tokens in a secure password vault for future access.

User sessions with authorizations

Optionally, when creating an authorization, you can scope it to a specific user. If the user signs in with username and password, creating a user session, the session carries the permissions granted by all the user's authorizations. For more information, see how to assign a token to a specific user. To create a user session, use the POST /api/v2/signin endpoint.

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

Content type
application/json
{
  • "authorizations": [
    ],
  • "links": {}
}

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

Content type
application/json
Example
An authorization for a resource type
An authorization for a resource type
An authorization for a resource
An authorization scoped to a user

Creates an authorization.

{
  • "description": "iot_users read buckets",
  • "orgID": "INFLUX_ORG_ID",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

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
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": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

Content type
application/json
{
  • "description": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "token": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "user": "string",
  • "userID": "string"
}

Bucket Schemas

List measurement schemas of a bucket

Lists explicit schemas ("schemaType": "explicit") for a bucket.

Explicit schemas are used to enforce column names, tags, fields, and data types for your data.

By default, buckets have an implicit schema-type ("schemaType": "implicit") that conforms to your data.

Authorizations:
TokenAuthentication
path Parameters
bucketID
required
string

A bucket ID. Lists measurement schemas for the specified bucket.

query Parameters
name
string

A measurement name. Only returns measurement schemas with the specified name.

org
string

An organization name. Specifies the organization that owns the schema.

orgID
string

An organization ID. Specifies the organization that owns the schema.

Responses

Response samples

Content type
application/json
{
  • "measurementSchemas": [
    ]
}

Create a measurement schema for a bucket

Creates an explicit measurement schema for a bucket.

Explicit schemas are used to enforce column names, tags, fields, and data types for your data.

By default, buckets have an implicit schema-type ("schemaType": "implicit") that conforms to your data.

Use this endpoint to create schemas that prevent non-conforming write requests.

Limitations

  • Buckets must be created with the "explicit" schemaType in order to use schemas.
Authorizations:
TokenAuthentication
path Parameters
bucketID
required
string

A bucket ID. Adds a schema for the specified bucket.

query Parameters
org
string

An organization name. Specifies the organization that owns the schema.

orgID
string

An organization ID. Specifies the organization that owns the schema.

Request Body schema: application/json
required
Array of objects (MeasurementSchemaColumn)

Ordered collection of column definitions.

name
required
string

The measurement name.

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ],
  • "name": "cpu"
}

Response samples

Content type
application/json
{
  • "bucketID": "ba3c5e7f9b0a0010",
  • "columns": [
    ],
  • "createdAt": "2021-01-21T00:48:40.993Z",
  • "id": "1a3c5e7f9b0a8642",
  • "name": "cpu",
  • "orgID": "0a3c5e7f9b0a0001",
  • "updatedAt": "2021-01-21T00:48:40.993Z"
}

Retrieve a measurement schema

Retrieves an explicit measurement schema.

Authorizations:
TokenAuthentication
path Parameters
bucketID
required
string

A bucket ID. Retrieves schemas for the specified bucket.

measurementID
required
string

The measurement schema ID. Specifies the measurement schema to retrieve.

query Parameters
org
string

Organization name. Specifies the organization that owns the schema.

orgID
string

Organization ID. Specifies the organization that owns the schema.

Responses

Response samples

Content type
application/json
{
  • "bucketID": "ba3c5e7f9b0a0010",
  • "columns": [
    ],
  • "createdAt": "2021-01-21T00:48:40.993Z",
  • "id": "1a3c5e7f9b0a8642",
  • "name": "cpu",
  • "orgID": "0a3c5e7f9b0a0001",
  • "updatedAt": "2021-01-21T00:48:40.993Z"
}

Update a measurement schema

Updates a measurement schema.

Use this endpoint to update the fields (name, type, and dataType) of a measurement schema.

Limitations

  • You can't update the name of a measurement.
Authorizations:
TokenAuthentication
path Parameters
bucketID
required
string

A bucket ID. Specifies the bucket to retrieve schemas for.

measurementID
required
string

A measurement schema ID. Retrieves the specified measurement schema.

query Parameters
org
string

An organization name. Specifies the organization that owns the schema.

orgID
string

An organization ID. Specifies the organization that owns the schema.

Request Body schema: application/json
required
Array of objects (MeasurementSchemaColumn)

An ordered collection of column definitions

Responses

Request samples

Content type
application/json
{
  • "columns": [
    ]
}

Response samples

Content type
application/json
{
  • "bucketID": "ba3c5e7f9b0a0010",
  • "columns": [
    ],
  • "createdAt": "2021-01-21T00:48:40.993Z",
  • "id": "1a3c5e7f9b0a8642",
  • "name": "cpu",
  • "orgID": "0a3c5e7f9b0a0001",
  • "updatedAt": "2021-01-21T00:48:40.993Z"
}

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.

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

ActionPermission required
Retrieve user bucketsread-buckets
Retrieve system bucketsread-orgs
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 --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

Content type
application/json
{
  • "buckets": [
    ],
  • "links": {
    }
}

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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "retentionRules": [
    ],
  • "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": {
    },
  • "name": "air_sensor",
  • "orgID": "INFLUX_ORG_ID",
  • "retentionRules": [
    ],
  • "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.
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 --request DELETE "http://localhost:8086/api/v2/buckets/BUCKET_ID" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --header 'Accept: application/json'

Response samples

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

Content type
application/json
{
  • "createdAt": "2022-08-03T23:04:41.073704121Z",
  • "description": "bucket for air sensor data",
  • "id": "37407e232b3911d8",
  • "labels": [ ],
  • "links": {
    },
  • "name": "air-sensor",
  • "orgID": "bea7ea952287f70d",
  • "retentionRules": [
    ],
  • "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.
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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "retentionRules": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-08-03T23:04:41.073704121Z",
  • "description": "bucket holding air sensor data",
  • "id": "37407e232b3911d8",
  • "labels": [ ],
  • "links": {
    },
  • "name": "air_sensor",
  • "orgID": "INFLUX_ORG_ID",
  • "retentionRules": [
    ],
  • "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.

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": [
    ],
  • "links": {
    }
}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{
  • "label": {
    },
  • "links": {
    }
}

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

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": {
    },
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "09cfb87051cbe000",
  • "links": {
    },
  • "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

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

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:
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": {
    },
  • "users": [
    ]
}

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

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

Content type
application/json
{
  • "id": "d88d182d91b0950f",
  • "links": {
    },
  • "name": "example-user",
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized access"
}

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

Content type
application/json
{
  • "h": 0,
  • "name": "string",
  • "usingView": "string",
  • "w": 0,
  • "x": 0,
  • "y": 0
}

Response samples

Content type
application/json
{
  • "h": 0,
  • "id": "string",
  • "links": {
    },
  • "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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "cells": [
    ],
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

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

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

Content type
application/json
{
  • "h": 0,
  • "w": 0,
  • "x": 0,
  • "y": 0
}

Response samples

Content type
application/json
{
  • "h": 0,
  • "id": "string",
  • "links": {
    },
  • "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

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

Content type
application/json
{
  • "checks": [
    ],
  • "links": {}
}

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

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "description": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "query": {
    },
  • "status": "active",
  • "taskID": "string",
  • "type": "custom"
}

Response samples

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "query": {
    },
  • "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

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

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "query": {
    },
  • "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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "status": "active"
}

Response samples

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "query": {
    },
  • "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

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "description": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "query": {
    },
  • "status": "active",
  • "taskID": "string",
  • "type": "custom"
}

Response samples

Content type
application/json
Example
custom
custom
deadman
threshold
Check
PostCheck
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "query": {
    },
  • "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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{
  • "flux": "string"
}

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:

  1. Use token authentication or a user session with this endpoint to retrieve feature flags and their values.

  2. Follow the instructions to enable, disable, or override values for feature flags.

  3. 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.
Authorizations:
TokenAuthentication
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
{ }

Dashboards

List dashboards

Lists 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

The maximum number of dashboards to return. Default is 20. The minimum is -1 and the maximum is 100.

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

Content type
application/json
{
  • "dashboards": [
    ],
  • "links": {}
}

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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string"
}

Response samples

Content type
application/json
Example
Dashboard
Dashboard
DashboardWithViewProperties
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "cells": [
    ],
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

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

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

Content type
application/json
Example
Dashboard
Dashboard
DashboardWithViewProperties
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "cells": [
    ],
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

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

Content type
application/json
{
  • "cells": {
    },
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "cells": [
    ],
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

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

Content type
application/json
{
  • "h": 0,
  • "name": "string",
  • "usingView": "string",
  • "w": 0,
  • "x": 0,
  • "y": 0
}

Response samples

Content type
application/json
{
  • "h": 0,
  • "id": "string",
  • "links": {
    },
  • "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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "cells": [
    ],
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

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

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

Content type
application/json
{
  • "h": 0,
  • "w": 0,
  • "x": 0,
  • "y": 0
}

Response samples

Content type
application/json
{
  • "h": 0,
  • "id": "string",
  • "links": {
    },
  • "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

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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.

List database retention policy mappings

Lists database retention policy (DBRP) mappings.

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

Content type
application/json
{
  • "content": [
    ]
}

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.

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

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.

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

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.

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

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.

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

Content type
application/json
{
  • "default": true,
  • "retention_policy": "string"
}

Response samples

Content type
application/json
{
  • "content": {
    }
}

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.

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.

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

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

Content type
application/json
{
  • "code": "invalid",
  • "message": "failed to decode request body: organization not found"
}

Invokable Scripts

Store, manage, and execute scripts in InfluxDB. A script stores your custom Flux script and provides an invokable endpoint that accepts runtime parameters. In a script, you can specify custom runtime parameters (params)--for example, params.myparameter. Once you create a script, InfluxDB generates an /api/v2/scripts/SCRIPT_ID/invoke endpoint for your organization. You can run the script from API requests and tasks, defining parameter values for each run. When the script runs, InfluxDB replaces params references in the script with the runtime parameter values you define.

Use the /api/v2/scripts endpoints to create and manage scripts. See related guides to learn how to define parameters and execute scripts.

List scripts

Lists scripts.

Authorizations:
TokenAuthentication
query Parameters
limit
integer [ 0 .. 500 ]
Default: 100

The maximum number of scripts to return. Default is 100.

name
string

The script name. Lists scripts 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.

Responses

Request samples

curl --request GET "INFLUX_URL/api/v2/scripts?limit=100&offset=0" \
  --header "Authorization: Token INFLUX_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "scripts": [
    ]
}

Create a script

Creates an invokable script and returns the script.

Authorizations:
TokenAuthentication
Request Body schema: application/json

The script to create.

description
required
string

Script description. A description of the script.

language
required
string (ScriptLanguage)
Enum: "flux" "sql"
name
required
string

Script name. The name must be unique within the organization.

script
required
string

The script to execute.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "language": "flux",
  • "name": "string",
  • "script": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-07-17T23:43:26.660308Z",
  • "description": "getLastPoint finds the last point in a bucket",
  • "id": "09afa23ff13e4000",
  • "language": "flux",
  • "name": "getLastPoint",
  • "orgID": "bea7ea952287f70d",
  • "script": "from(bucket: params.mybucket) |> range(start: -7d) |> limit(n:1)",
  • "updatedAt": "2022-07-17T23:43:26.660308Z"
}

Delete a script

Deletes a script and all associated records.

Limitations

  • You can delete only one script per request.
  • If the script ID you provide doesn't exist for the organization, InfluxDB responds with an HTTP 204 status code.
Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Deletes the specified script.

Responses

Request samples

curl -X 'DELETE' \
  "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \
  --header "Authorization: Token INFLUX_TOKEN" \
  --header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized access"
}

Retrieve a script

Retrieves a script.

Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Retrieves the specified script.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2022-07-17T23:49:45.731237Z",
  • "description": "getLastPoint finds the last point in a bucket",
  • "id": "09afa3b220fe4000",
  • "language": "flux",
  • "name": "getLastPoint",
  • "orgID": "bea7ea952287f70d",
  • "script": "from(bucket: my-bucket) |> range(start: -7d) |> limit(n:1)",
  • "updatedAt": "2022-07-17T23:49:45.731237Z"
}

Update a script

Updates an invokable script.

Use this endpoint to modify values for script properties (description and script).

To update a script, pass an object that contains the updated key-value pairs.

Limitations

  • If you send an empty request body, the script will neither update nor store an empty script, but InfluxDB will respond with an HTTP 200 status code.
Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Updates the specified script.

Request Body schema: application/json

An object that contains the updated script properties to apply.

description
string

A description of the script.

script
string

The script to execute.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "script": "string"
}

Response samples

Content type
application/json
{
  • "createdAt": "2022-07-17T23:49:45.731237Z",
  • "description": "get last point from new bucket",
  • "id": "09afa3b220fe4000",
  • "language": "flux",
  • "name": "getLastPoint",
  • "orgID": "bea7ea952287f70d",
  • "script": "from(bucket: newBucket) |> range(start: -7d) |> limit(n:1)",
  • "updatedAt": "2022-07-19T22:27:23.185436Z"
}

Invoke a script

Runs a script and returns the result. When the script runs, InfluxDB replaces params keys referenced in the script with params key-values passed in the request body--for example:

The following sample script contains a mybucket parameter :

"script": "from(bucket: params.mybucket)
            |> range(start: -7d)
            |> limit(n:1)"

The following example POST /api/v2/scripts/SCRIPT_ID/invoke request body passes a value for the mybucket parameter:

{
  "params": {
    "mybucket": "air_sensor"
  }
}
Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. Runs the specified script.

Request Body schema: application/json
object

The script parameters. params contains key-value pairs that map values to the params.keys in a script. When you invoke a script with params, InfluxDB passes the values as invocation parameters to the script.

Responses

Request samples

Content type
application/json
{
  • "params": { }
}

Response samples

Content type
text/csv
,result,table,_start,_stop,_time,_value,_field,_measurement,host
,_result,0,2019-10-30T01:28:02.52716421Z,2022-07-26T01:28:02.52716421Z,2020-01-01T00:00:00Z,72.01,used_percent,mem,host2

Find script parameters.

Analyzes a script and determines required parameters. Find all params keys referenced in a script and return a list of keys. If it is possible to determine the type of the value from the context then the type is also returned -- for example:

The following sample script contains a mybucket parameter :

"script": "from(bucket: params.mybucket)
            |> range(start: -7d)
            |> limit(n:1)"

Requesting the parameters using GET /api/v2/scripts/SCRIPT_ID/params returns the following:

{
  "params": {
    "mybucket": "string"
  }
}

The type name returned for a parameter will be one of:

  • any
  • bool
  • duration
  • float
  • int
  • string
  • time
  • uint

The type name any is used when the type of a parameter cannot be determined from the context, or the type is determined to be a structured type such as an array or record.

Authorizations:
TokenAuthentication
path Parameters
scriptID
required
string

A script ID. The script to analyze for params.

Responses

Request samples

curl --request GET "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID/params" \
          --header "Authorization: Token INFLUX_TOKEN"

Response samples

Content type
application/json
{
  • "params": {
    }
}

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

Content type
application/json
{}

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

Content type
application/json
{
  • "name": "string",
  • "orgID": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{}

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

Content type
application/json
{
  • "name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{}

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

Content type
application/json
{
  • "authorizations": [
    ],
  • "links": {}
}

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

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "orgID": "string",
  • "permissions": [
    ],
  • "token": "string",
  • "userID": "string"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

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

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

Content type
application/json
{
  • "description": "string",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "description": "string",
  • "status": "active",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "links": {
    },
  • "org": "string",
  • "orgID": "string",
  • "permissions": [
    ],
  • "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

Content type
application/json
{
  • "password": "string"
}

Response samples

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

Content type
application/csv
application/csv
application/json
application/x-msgpack
text/csv
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

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "line": 0,
  • "message": "string",
  • "op": "string"
}

Limits

Retrieve limits for an organization

Authorizations:
TokenAuthentication
path Parameters
orgID
required
string

The ID of the organization.

Responses

Response samples

Content type
application/json
{
  • "limits": {
    },
  • "links": {}
}

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

Content type
application/json
{
  • "links": {},
  • "notificationEndpoints": [
    ]
}

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

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "method": "POST",
  • "password": "string",
  • "token": "string",
  • "url": "string",
  • "username": "string"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "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

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

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "status": "active"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "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

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "method": "POST",
  • "password": "string",
  • "token": "string",
  • "url": "string",
  • "username": "string"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
telegram
NotificationEndpoint
PostNotificationEndpoint
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    },
  • "name": "string",
  • "orgID": "string",
  • "status": "active",
  • "type": "http",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "userID": "string",
  • "authMethod": "none",
  • "contentTemplate": "string",
  • "headers": {
    },
  • "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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{
  • "links": {},
  • "notificationRules": [
    ]
}

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

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "labels": [
    ],
  • "limit": 0,
  • "limitEvery": 0,
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "taskID": "string",
  • "type": "http",
  • "url": "string"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "limit": 0,
  • "limitEvery": 0,
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "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

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

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "limit": 0,
  • "limitEvery": 0,
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "status": "active"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "limit": 0,
  • "limitEvery": 0,
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "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

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "labels": [
    ],
  • "limit": 0,
  • "limitEvery": 0,
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "taskID": "string",
  • "type": "http",
  • "url": "string"
}

Response samples

Content type
application/json
Example
http
http
pagerduty
slack
smtp
telegram
NotificationRule
PostNotificationRule
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "endpointID": "string",
  • "every": "string",
  • "id": "string",
  • "labels": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "limit": 0,
  • "limitEvery": 0,
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "runbookLink": "string",
  • "sleepUntil": "string",
  • "status": "active",
  • "statusRules": [
    ],
  • "tagRules": [
    ],
  • "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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "message": "string",
  • "op": "string"
}

Organizations

Manage your organization. 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 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.
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": {
    },
  • "orgs": [
    ]
}

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

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": {
    },
  • "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.
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

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.

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

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "defaultStorageType": "tsm",
  • "description": "string",
  • "id": "string",
  • "links": {
    },
  • "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.

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

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": {
    },
  • "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

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": {
    },
  • "users": [
    ]
}

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

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "09cfb87051cbe000",
  • "links": {
    },
  • "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

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.

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

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized access"
}

List all owners of an organization

Lists all owners of an organization.

InfluxDB Cloud

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

Content type
application/json
{
  • "links": {
    },
  • "users": [
    ]
}

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

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

Content type
application/json
{
  • "id": "09cfb87051cbe000",
  • "links": {
    },
  • "name": "example_user_1",
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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

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.

Authorizations:
TokenAuthentication

Responses

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.

Authorizations:
TokenAuthentication

Responses

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.

object

Key-value pairs passed as parameters during query execution.

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

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

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

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

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

Limitations

  • If you use params, you can't use extern.
query
required
string

The query script to execute.

type
string
Value: "flux"

The type of query. Must be "flux".

Responses

Request samples

Content type
application/json
application/json
application/vnd.flux
{
  • "dialect": {
    },
  • "extern": {
    },
  • "now": "2019-08-24T14:15:22Z",
  • "params": { },
  • "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.

object

Key-value pairs passed as parameters during query execution.

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

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

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

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

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

Limitations

  • If you use params, you can't use extern.
query
required
string

The query script to execute.

type
string
Value: "flux"

The type of query. Must be "flux".

Responses

Request samples

Content type
application/json
{
  • "dialect": {
    },
  • "extern": {
    },
  • "now": "2019-08-24T14:15:22Z",
  • "params": { },
  • "query": "string",
  • "type": "flux"
}

Response samples

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": [
    ]
}

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

Content type
application/json
{
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "ast": {
    }
}

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.
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 --request GET "INFLUX_URL/api/v2/query/suggestions" \
  --header "Accept: application/json" \
  --header "Authorization: Token INFLUX_API_TOKEN"

Response samples

Content type
application/json
{
  • "funcs": [
    ]
}

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.

Authorizations:
TokenAuthentication
path Parameters
name
required
string
header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "name": "sum",
  • "params": {
    }
}

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

Content type
application/json
[
  • "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

Content type
application/json
{}

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

Content type
application/json
{
  • "flux": "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

Content type
application/json
{
  • "secrets": [
    ],
  • "links": {
    }
}

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

Content type
application/json
{
  • "apikey": "abc123xyz"
}

Response samples

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

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

Content type
application/json
{
  • "secrets": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "message": "string",
  • "op": "string"
}

Setup

Retrieve setup status

Check if setup is allowed. Returns true if no default user, organization, or bucket have 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

Content type
application/json
{
  • "allowed": true
}

Create an initial user, organization, and bucket

Post an onboarding request to create an initial user, organization, 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
object (Limit)

These are org limits similar to those configured in/by quartz.

org
required
string
password
string
retentionPeriodHrs
integer
Deprecated
retentionPeriodSeconds
integer
username
required
string

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "limit": {
    },
  • "org": "string",
  • "password": "string",
  • "retentionPeriodHrs": 0,
  • "retentionPeriodSeconds": 0,
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "auth": {
    },
  • "bucket": {
    },
  • "org": {
    },
  • "user": {
    }
}

Create a new user, organization, and bucket

Post an onboarding request to create a new user, organization, and bucket.

Authorizations:
TokenAuthentication
Request Body schema: application/json

Source to create

bucket
required
string
object (Limit)

These are org limits similar to those configured in/by quartz.

org
required
string
password
string
retentionPeriodHrs
integer
Deprecated
retentionPeriodSeconds
integer
username
required
string

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "limit": {
    },
  • "org": "string",
  • "password": "string",
  • "retentionPeriodHrs": 0,
  • "retentionPeriodSeconds": 0,
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "auth": {
    },
  • "bucket": {
    },
  • "org": {
    },
  • "user": {
    }
}

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.
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 --request POST http://localhost:8086/api/v2/signin \
     --user "USERNAME:PASSWORD"

Response samples

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:

  1. 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.
  2. Send a request to the GET /api/v2/me endpoint, passing the stored session cookie from step 1 to retrieve user information.
  3. 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.

Authorizations:
TokenAuthentication
header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

Request samples

# 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

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "message": "string",
  • "op": "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 this 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
string <flux>

The Flux script that the task executes.

Limitations

  • If you use the flux property, you can't use the scriptID and scriptParameters properties.
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.

scriptID
string

A script ID. Specifies the invokable script that the task executes.

Limitations

  • If you use the scriptID property, you can't use the flux property.
scriptParameters
object

Key-value pairs for params in the script. Defines the invocation parameter values passed to the script specified by scriptID. When running the task, InfluxDB executes the script with the parameters you provide.

Limitations

  • To use scriptParameters, you must provide a scriptID.
  • If you use the scriptID and scriptParameters properties, you can't use the flux property.
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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "status": "active",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List all 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.

Authorizations:
TokenAuthentication
query Parameters
after
string

A task ID. Only returns tasks created after the specified task.

limit
integer [ -1 .. 500 ]
Default: 100
Examples:
  • limit=-1 - Return all tasks, without pagination.
  • limit=50 - Return a maximum of 50 tasks.

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.

offset
integer >= 0
Default: 0

The number of records to skip.

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.

scriptID
string

A script ID. Only returns tasks that use the specified invokable script.

sortBy
string
Value: "name"

The sort field. Only name is supported. Specifies the field used to sort records in the list.

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 INFLUX_URL/api/v2/tasks/?limit=-1&type=basic \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token INFLUX_API_TOKEN'

Response samples

Content type
application/json
Example
Basic output
Basic output
System output

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": {
    },
  • "tasks": [
    ]
}

Create a task

Creates a task and returns the task.

Use this endpoint to create a scheduled task that runs a Flux script.

InfluxDB Cloud

  • You can use either flux or scriptID to provide the task script.

    • flux: a string of "raw" Flux that contains task options and the script--for example:

      {
  "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\
  from(bucket: \"telegraf\")
    |> range(start: -1h)
    |> filter(fn: (r) => (r._measurement == \"cpu\"))
    |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))
    |> filter(fn: (r) => (r.cpu == \"cpu-total\"))
    |> aggregateWindow(every: 1h, fn: max)
    |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")",
  "status": "active",
  "description": "This task downsamples CPU data every hour"
}

    • scriptID: the ID of an invokable script for the task to run. To pass task options when using scriptID, pass the options as properties in the request body--for example:

      {
  "name": "CPU Total 1 Hour New",
  "description": "This task downsamples CPU data every hour",
  "every": "1h",
  "scriptID": "SCRIPT_ID",
  "scriptParameters":
    {
      "rangeStart": "-1h",
      "bucket": "telegraf",
      "filterField": "cpu-total"
    }
  }

Limitations:

  • You can't use flux and scriptID for the same 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

cron
string

A Cron expression that defines the schedule on which the task runs. InfluxDB bases cron runs on the system time.

description
string

The description of the task.

every
string

The interval (duration literal)) at which the task runs. every also determines when the task first runs, depending on the specified time.

flux
string

The Flux script that the task runs.

Limitations

  • If you use the flux property, you can't use the scriptID and scriptParameters properties.
name
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

The name of the organization that owns the task.

orgID
string

The ID of the organization that owns the task.

scriptID
string

The ID of the script that the task runs.

Limitations

  • If you use the scriptID property, you can't use the flux property.
scriptParameters
object

The parameter key-value pairs passed to the script (referenced by scriptID) during the task run.

Limitations

  • scriptParameters requires scriptID.
  • If you use the scriptID and scriptParameters properties, you can't use the flux property.
status
string (TaskStatusType)
Enum: "active" "inactive"

inactive cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Content type
application/json
{
  • "cron": "string",
  • "description": "string",
  • "every": "string",
  • "flux": "string",
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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

A task ID. Specifies 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

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

A task ID. Specifies 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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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, or 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.

InfluxDB Cloud

  • Use either flux or scriptID to provide the task script.

    • flux: a string of "raw" Flux that contains task options and the script--for example:

      {
  "flux": "option task = {name: \"CPU Total 1 Hour New\", every: 1h}\
  from(bucket: \"telegraf\")
    |> range(start: -1h)
    |> filter(fn: (r) => (r._measurement == \"cpu\"))
    |> filter(fn: (r) =>\n\t\t(r._field == \"usage_system\"))
    |> filter(fn: (r) => (r.cpu == \"cpu-total\"))
    |> aggregateWindow(every: 1h, fn: max)
    |> to(bucket: \"cpu_usage_user_total_1h\", org: \"INFLUX_ORG\")",
  "status": "active",
  "description": "This task downsamples CPU data every hour"
}

    • scriptID: the ID of an invokable script for the task to run. To pass task options when using scriptID, pass the options as properties in the request body--for example:

      {
  "name": "CPU Total 1 Hour New",
  "description": "This task downsamples CPU data every hour",
  "every": "1h",
  "scriptID": "SCRIPT_ID",
  "scriptParameters":
    {
      "rangeStart": "-1h",
      "bucket": "telegraf",
      "filterField": "cpu-total"
    }
  }

Limitations:

  • You can't use flux and scriptID for the same task.
Authorizations:
TokenAuthentication
path Parameters
taskID
required
string

A task ID. Specifies 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 task update 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

Update 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.

scriptID
string

Update the 'scriptID' of the task.

scriptParameters
object

Update the 'scriptParameters' of the task.

status
string (TaskStatusType)
Enum: "active" "inactive"

inactive cancels scheduled runs and prevents manual runs of the task.

Responses

Request samples

Content type
application/json
{
  • "cron": "string",
  • "description": "string",
  • "every": "string",
  • "flux": "string",
  • "name": "string",
  • "offset": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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": [
    ],
  • "lastRunError": "string",
  • "lastRunStatus": "failed",
  • "latestCompleted": "2019-08-24T14:15:22Z",
  • "links": {
    },
  • "name": "string",
  • "offset": "string",
  • "org": "string",
  • "orgID": "string",
  • "ownerID": "string",
  • "scriptID": "string",
  • "scriptParameters": { },
  • "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
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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 for a failed task run.
Events for a failed task run.
Events for a successful task run.
{
  • "events": [
    ]
}

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "0772396d1f411000",
  • "links": {
    },
  • "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

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

Content type
application/json
{
  • "links": {},
  • "runs": [
    ]
}

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

Content type
application/json
{
  • "scheduledFor": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "finishedAt": "2006-01-02T15:04:05.999999999Z07:00",
  • "flux": "string",
  • "id": "string",
  • "links": {
    },
  • "log": [
    ],
  • "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": {
    },
  • "log": [
    ],
  • "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 for a failed task.
Events for a failed task.
Events for a successful task run.
{
  • "events": [
    ]
}

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

Content type
application/json; charset=utf-8
{ }

Response samples

Content type
application/json
{
  • "id": "09d60ffe08738000",
  • "links": {
    },
  • "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

Content type
application/json
{
  • "os": "string",
  • "plugins": [
    ],
  • "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

Content type
application/json
{
  • "configurations": [
    ]
}

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

Content type
application/json
{
  • "config": "string",
  • "description": "string",
  • "metadata": {
    },
  • "name": "string",
  • "orgID": "string",
  • "plugins": [
    ]
}

Response samples

Content type
application/json
{
  • "config": "string",
  • "description": "string",
  • "metadata": {
    },
  • "name": "string",
  • "orgID": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    }
}

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

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

Content type
application/json
application/json
application/octet-stream
application/toml
{
  • "config": "string",
  • "description": "string",
  • "metadata": {
    },
  • "name": "string",
  • "orgID": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    }
}

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

Content type
application/json
{
  • "config": "string",
  • "description": "string",
  • "metadata": {
    },
  • "name": "string",
  • "orgID": "string",
  • "plugins": [
    ]
}

Response samples

Content type
application/json
{
  • "config": "string",
  • "description": "string",
  • "metadata": {
    },
  • "name": "string",
  • "orgID": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {
    }
}

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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

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

Content type
application/json
{
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

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 resources. Use InfluxDB templates to configure a fresh instance of InfluxDB, back up your dashboard configuration, or share your configuration.

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.

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

Content type
application/json
{
  • "stacks": [
    ]
}

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

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "orgID": "string",
  • "urls": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "events": [
    ],
  • "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

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

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "events": [
    ],
  • "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

Content type
application/json
{
  • "additionalResources": [
    ],
  • "description": "string",
  • "name": "string",
  • "templateURLs": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "events": [
    ],
  • "id": "string",
  • "orgID": "string"
}

Uninstall a stack

Authorizations:
TokenAuthentication
path Parameters
stack_id
required
string

The identifier of the stack.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "events": [
    ],
  • "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

Required permissions

  • write permissions for resource types in the template.

Rate limits (with InfluxDB Cloud)

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.

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.

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

Content type
application/json
application/json
application/x-jsonnet
text/yml
Example
Skip all bucket and task resources in the provided templates
Skip all bucket and task resources in the provided templates
Skip specific resources in the provided templates
envRefs for template objects
{
  • "actions": [
    ],
  • "orgID": "INFLUX_ORG_ID",
  • "templates": [
    ]
}

Response samples

Content type
application/json
{
  • "diff": {
    },
  • "errors": [
    ],
  • "sources": [
    ],
  • "stackID": "string",
  • "summary": {
    }
}

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

Content type
application/json
Example
TemplateExportByID
TemplateExportByID
TemplateExportByName
{
  • "orgIDs": [
    ],
  • "resources": [
    ],
  • "stackID": "string"
}

Response samples

Content type
application/json
application/json
application/x-yaml
[
  • {
    }
]

Usage

Retrieve usage for an organization

Authorizations:
TokenAuthentication
path Parameters
orgID
required
string

The ID of the organization.

query Parameters
raw
boolean
Default: false

return raw usage data

start
required
integer <unix timestamp>

Earliest time to include in results. For more information about timestamps, see Manipulate timestamps with Flux.

stop
integer <unix timestamp>

Latest time to include in results. For more information about timestamps, see Manipulate timestamps with Flux.

Responses

Response samples

Content type
application/json
{
  • "code": "internal error",
  • "err": "string",
  • "message": "string",
  • "op": "string"
}

Users

Retrieve specific users.

InfluxDB Cloud lets you invite and collaborate with multiple users in your organization. To invite and remove users from your organization, use the InfluxDB Cloud user interface (UI); you can't use the InfluxDB API to manage users in InfluxDB Cloud. Once a user is added to your organization, you can use the GET /api/v2/users and GET /api/v2/users/USER_ID API endpoints to view specific members.

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

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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:

  1. Pass the user's Basic authentication credentials to the POST /api/v2/signin endpoint to create a user session and generate a session cookie.
  2. From the response in the first step, extract the session cookie (Set-Cookie) header.
  3. 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.
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.

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

Content type
application/json
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "code": "unauthorized",
  • "message": "unauthorized access"
}

List users

Lists users.

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

InfluxDB Cloud

  • InfluxDB Cloud doesn't allow listing all users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions for InfluxDB Cloud

ActionPermission requiredRestriction
List all usersOperator tokenInfluxData internal use only
List a specific userread-users or read-user USER_ID

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

Authorizations:
TokenAuthentication
query Parameters
id
string

A user id. Only lists the specified user.

name
string

A user name. Only lists 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

Content type
application/json
{
  • "links": {},
  • "users": [
    ]
}

Create a user

(InfluxData internal use only)

Creates and returns a user that can access InfluxDB.

InfluxDB Cloud

  • InfluxDB Cloud Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions for InfluxDB Cloud

ActionPermission requiredRestriction
Create userOperator tokenInfluxData internal use only
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

In the request body, provide the user.

name
required
string
org_id
string
role
string
Enum: "owner" "member"
status
string
Default: "active"
Enum: "active" "inactive"

If inactive the user is inactive.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "org_id": "string",
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "status": "active"
}

Delete a user

(InfluxData internal use only)

Deletes a user.

For security purposes, once an InfluxDB user account is deleted from an organization, the user (and their token) cannot be reactivated.

InfluxDB Cloud

  • Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions

ActionPermission requiredRestriction
Delete userOperator tokenInfluxData internal use only
Authorizations:
TokenAuthentication
path Parameters
userID
required
string

A user ID. Deletes 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

Content type
application/json
{
  • "code": "invalid",
  • "message": "failed to decode request body: organization not found"
}

Retrieve a user

Retrieves a user.

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

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "status": "active"
}

Update a user

(InfluxData internal use only)

Updates a user and returns the user.

InfluxDB Cloud

  • Doesn't let you manage users through the API. Use the InfluxDB Cloud user interface (UI) to manage account information.

Required permissions for InfluxDB Cloud

ActionPermission requiredRestriction
Update userOperator tokenInfluxData internal use only
Authorizations:
TokenAuthentication
path Parameters
userID
required
string

A user ID. Updates the specified user.

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 update to apply.

name
required
string
org_id
string
role
string
Enum: "owner" "member"
status
string
Default: "active"
Enum: "active" "inactive"

If inactive the user is inactive.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "org_id": "string",
  • "role": "owner",
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "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

Content type
application/json
{
  • "password": "string"
}

Response samples

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

Content type
application/json
{
  • "password": "string"
}

Response samples

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

Content type
application/json
{
  • "variables": [
    ]
}

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
sort_order
integer
updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {},
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "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

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

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {},
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "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
sort_order
integer
updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {},
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "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
sort_order
integer
updatedAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "labels": [
    ],
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "arguments": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "labels": [
    ],
  • "links": {},
  • "name": "string",
  • "orgID": "string",
  • "selected": [
    ],
  • "sort_order": 0,
  • "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

Content type
application/json
{}

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

Content type
application/json
{
  • "labelID": "string"
}

Response samples

Content type
application/json
{}

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

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

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

Content type
application/json
{
  • "name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "links": {
    },
  • "name": "string",
  • "properties": {
    }
}

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

  1. Use gzip to compress the line protocol data.
  2. In your request, send the compressed data and the Content-Encoding: gzip header.
string <byte>

Responses

Request samples

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
(Cloud) field type conflict thrown by an explicit bucket schema
(Cloud) field type conflict thrown by an explicit bucket schema
(OSS) organization not found
{
  • "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"
}