InfluxDB OSS API Service (2.x)

License: MIT

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

The InfluxDB v2 HTTP API provides a programmatic interface for all interactions with an InfluxDB v2 instance. 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:

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

Encode credentials with cURL

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

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

Encode credentials with Flux

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

Encode credentials with JavaScript

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

  1. btoa('USERNAME:PASSWORD')

The output is the following:

  1. 'VVNFUk5BTUU6UEFTU1dPUkQ='

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

  1. curl --get "INFLUX_URL/api/v2/signin"
  2.     --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:

  1. curl --request GET "INFLUX_URL/api/v2/buckets" \
  2.     --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:

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

    The response contains the following:

    1. {
    2.   "links": {
    3.       "prev": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=49\u0026orgID=ORG_ID",
    4.       "self": "/api/v2/buckets?descending=false\u0026limit=1\u0026offset=50\u0026orgID=ORG_ID"
    5.   },
    6.   "buckets": []
    7. }

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
204Success. No contentInfluxDB doesn’t return data for the request.
400Bad requestMay indicate one of the following:
  • Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the rejected_points measurement in your _monitoring bucket.
  • Authorization header is missing or malformed or the API token doesn’t have permission for the operation.
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.
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

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the delete asynchronously - the deletion might not have completed yet.

An HTTP 2xx status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request.

Because writes are asynchronous, data might not yet be written when you receive the response.

InfluxDB OSS

  • Deleted the data.

v2 API - 图1400

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

InfluxDB OSS

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

v2 API - 图2401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图3404

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

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

v2 API - 图4500

Internal server error. The server encountered an unexpected situation.

v2 API - 图5default

Non 2XX error response from server.

post/api/v2/deletev2 API - 图6

/api/v2/delete

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图7

application/json

application/vnd.flux

Flux query or specification to execute

object (Dialect)

Options for tabular data output. Default output is annotated CSV with headers.

For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.

object (File)

Represents a source from a single file

now
string <date-time>

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

query
required
string

The query script to execute.

type
string
Value: “flux”

The type of query. Must be “flux”.

Responses

v2 API - 图10200

Success. The response body contains query results.

v2 API - 图11400

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

InfluxDB OSS

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

v2 API - 图12401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图13404

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

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

v2 API - 图14429

InfluxDB Cloud:

  • returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit
  • returns Retry-After header that describes when to try the write again.

InfluxDB OSS:

  • doesn’t return this error.

v2 API - 图15500

Internal server error. The server encountered an unexpected situation.

v2 API - 图16default

Non 2XX error response from server.

post/api/v2/queryv2 API - 图17

/api/v2/query

Request samples

  • Payload
  • cURL

Content type

application/json

v2 API - 图18

application/json

application/vnd.flux

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/csv

Copy

  1. result,table,_start,_stop,_time,region,host,_value
  2. mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
  3. mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
  4. mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:40Z,east,C,52.62

List tasks

Retrieves a list of tasks.

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

Authorizations:

TokenAuthentication

query Parameters
after
string

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

limit
integer [ 1 .. 500 ]
Default: 100

The maximum number of tasks to return. Default is 100. The minimum is 1 and the maximum is 500.

To reduce the payload size, combine type=basic and limit (see Request samples). For more information about the basic response, see the type parameter.

name
string

A task name. Only returns tasks with the specified name. Different tasks may have the same name.

org
string

An organization name. Only returns tasks owned by the specified organization.

orgID
string

An organization ID. Only returns tasks owned by the specified organization.

status
string
Enum: “active” “inactive”

A task status. Only returns tasks that have the specified status (active or inactive).

type
string
Default: “”
Enum: “basic” “system”

A task type (basic or system). Default is system. Specifies the level of detail for tasks in the response. The default (system) response contains all the metadata properties for tasks. To reduce the response size, pass basic to omit some task properties (flux, createdAt, updatedAt).

user
string

A user ID. Only returns tasks owned by the specified user.

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

OpenTracing span context

Responses

v2 API - 图19200

Success. The response body contains the list of tasks.

v2 API - 图20401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图21500

Internal server error. The server encountered an unexpected situation.

v2 API - 图22default

Non 2XX error response from server.

get/api/v2/tasksv2 API - 图23

/api/v2/tasks

Request samples

  • cURL: all tasks, basic output

Copy

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

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Example

Basic output

v2 API - 图24

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.

Copy

Expand all Collapse all

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

Create a task

Creates a task and returns the task.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

The task to create.

description
string

An optional description of the task.

flux
required
string

The Flux script to run for this task.

org
string

The name of the organization that owns this Task.

orgID
string

The ID of the organization that owns this Task.

status
string (TaskStatusType)
Enum: “active” “inactive”

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

Responses

v2 API - 图25201

Success. The response body contains a tasks list with the task.

v2 API - 图26400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed for org or orgID.

v2 API - 图27401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图28500

Internal server error. The server encountered an unexpected situation.

v2 API - 图29default

Unexpected error

post/api/v2/tasksv2 API - 图30

/api/v2/tasks

Request samples

  • Payload
  • cURL: create a task

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a task

Retrieves a task.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to retrieve.

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

OpenTracing span context

Responses

v2 API - 图31200

Success. The response body contains the task.

v2 API - 图32400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图33401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图34404

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

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

v2 API - 图35500

Internal server error. The server encountered an unexpected situation.

v2 API - 图36default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}v2 API - 图37

/api/v2/tasks/{taskID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Start a task run, overriding the schedule

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

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

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json
scheduledFor
string or null <date-time>

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

Responses

v2 API - 图38201

Success. The run is scheduled to start.

v2 API - 图39401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图40500

Internal server error. The server encountered an unexpected situation.

v2 API - 图41default

Non 2XX error response from server.

post/api/v2/tasks/{taskID}/runsv2 API - 图42

/api/v2/tasks/{taskID}/runs

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Write data

Writes data to a bucket.

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

InfluxDB Cloud

  • Does the following when you send a write request:

    1. Validates the request and queues the write.
    2. If queued, responds with success (HTTP 2xx status code); error otherwise.
    3. Handles the delete asynchronously and reaches eventual consistency.

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

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

InfluxDB OSS

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

Required permissions

  • write-buckets or write-bucket BUCKET_ID.

    BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

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

Authorizations:

TokenAuthentication

query Parameters
bucket
required
string

A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket.

org
required
string

An organization name or ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
orgID
string

An organization ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
precision
string (WritePrecision)
Enum: “ms” “s” “us” “ns”

The precision for unix timestamps in the line protocol batch.

header Parameters
Accept
string
Default: application/json
Value: “application/json”

The content type that the client can understand. Writes only return a response body if they fail—for example, due to a formatting problem or quota limit.

InfluxDB Cloud

  • Returns only application/json for format and limit errors.
  • Returns only text/html for some quota limit errors.

InfluxDB OSS

  • Returns only application/json for format and limit errors.

Related guides

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

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the write asynchronously - the write might not have completed yet.

InfluxDB OSS

  • Successfully wrote all points in the batch.

v2 API - 图43400

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

InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected.

InfluxDB Cloud

  • Returns this error for bucket schema conflicts.

InfluxDB OSS

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

v2 API - 图44401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图45404

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

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

v2 API - 图46413

The request payload is too large. InfluxDB rejected the batch and did not write any data.

InfluxDB Cloud:

  • Returns this error if the payload exceeds the 50MB size limit.
  • Returns Content-Type: text/html for this error.

InfluxDB OSS:

  • Returns this error only if the Go (golang) ioutil.ReadAll() function raises an error.
  • Returns Content-Type: application/json for this error.

v2 API - 图47429

Too many requests.

InfluxDB Cloud

  • Returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit.

  • For rate limits that reset automatically, returns a Retry-After header that describes when to try the write again.

  • For limits that can’t reset (for example, cardinality limit), doesn’t return a Retry-After header.

    Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.

InfluxDB OSS

  • Doesn’t return this error.

v2 API - 图48500

Internal server error. The server encountered an unexpected situation.

v2 API - 图49503

Service unavailable.

  • Returns this error if the server is temporarily unavailable to accept writes.
  • Returns a Retry-After header that describes when to try the write again.

v2 API - 图50default

Non 2XX error response from server.

post/api/v2/writev2 API - 图51

/api/v2/write

Request samples

  • Payload

Content type

text/plain

Copy

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

Response samples

  • 400
  • 401
  • 404
  • 413
  • 500
  • default

Content type

application/json

Example

(Cloud) field type conflict thrown by an explicit bucket schema

v2 API - 图52

(Cloud) field type conflict thrown by an explicit bucket schema

(OSS) organization not found

Copy

Expand all Collapse all

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

v2 API - 图53200

Success. The response body contains a list of authorizations.

If the response body is missing authorizations that you expect, check that the API token used in the request has read-user permission for the users (userID property value) in those authorizations.

InfluxDB OSS

  • Warning: The response body contains authorizations with their API token values in clear text.
  • If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.

v2 API - 图54400

Non 2XX error response from server.

v2 API - 图55401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图56500

Internal server error. The server encountered an unexpected situation.

v2 API - 图57default

Non 2XX error response from server.

get/api/v2/authorizationsv2 API - 图58

/api/v2/authorizations

Response samples

  • 200
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create an authorization

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

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

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

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

We recommend the following for managing your tokens:

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

Required permissions

  • write-authorizations
  • write-user for the user that the authorization is scoped to
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

v2 API - 图60201

Success. The authorization is created. The response body contains the authorization.

v2 API - 图61400

Non 2XX error response from server.

v2 API - 图62401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图63500

Internal server error. The server encountered an unexpected situation.

v2 API - 图64default

Non 2XX error response from server.

post/api/v2/authorizationsv2 API - 图65

/api/v2/authorizations

Request samples

  • Payload

Content type

application/json

Example

An authorization for a resource type

v2 API - 图66

An authorization for a resource type

An authorization for a resource

An authorization scoped to a user

Creates an authorization.

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete an authorization

Deletes an authorization.

Use the endpoint to delete an API token.

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

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

An authorization ID. Specifies the authorization to delete.

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

OpenTracing span context

Responses

204

Success. The authorization is deleted.

v2 API - 图67400

Bad request.

v2 API - 图68401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图69404

Not found.

v2 API - 图70500

Internal server error. The server encountered an unexpected situation.

v2 API - 图71default

Non 2XX error response from server.

delete/api/v2/authorizations/{authID}v2 API - 图72

/api/v2/authorizations/{authID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图73200

Success. The response body contains the authorization.

v2 API - 图74400

Bad request.

v2 API - 图75401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图76404

Not found.

v2 API - 图77500

Internal server error. The server encountered an unexpected situation.

v2 API - 图78default

Non 2XX error response from server.

get/api/v2/authorizations/{authID}v2 API - 图79

/api/v2/authorizations/{authID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update an API token to be active or inactive

Updates an authorization.

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

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

An authorization ID. Specifies the authorization to update.

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

OpenTracing span context

Request Body schema: application/json

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

description
string

A description of the token.

status
string
Default: “active”
Enum: “active” “inactive”

Status of the token. If inactive, InfluxDB rejects requests that use the token.

Responses

v2 API - 图80200

Success. The response body contains the updated authorization.

v2 API - 图81default

Non 2XX error response from server.

patch/api/v2/authorizations/{authID}v2 API - 图82

/api/v2/authorizations/{authID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List organizations

Lists organizations.

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

InfluxDB Cloud

  • Only returns the organization that owns the token passed in the request.
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

v2 API - 图83200

Success. The response body contains a list of organizations.

v2 API - 图84400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图85401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图86404

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

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

v2 API - 图87500

Internal server error. The server encountered an unexpected situation.

v2 API - 图88default

Non 2XX error response from server.

get/api/v2/orgsv2 API - 图89

/api/v2/orgs

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve an organization

Retrieves an organization.

Use this endpoint to retrieve information for a specific organization.

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

v2 API - 图90200

Success. The response body contains the organization information.

v2 API - 图91401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图92404

Not found. Organization not found.

v2 API - 图93500

Internal server error. The server encountered an unexpected situation.

v2 API - 图94default

Unexpected error

get/api/v2/orgs/{orgID}v2 API - 图95

/api/v2/orgs/{orgID}

Response samples

  • 200
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all members of an organization

Lists all users that belong to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

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

v2 API - 图96200

Success. The response body contains a list of all users within the organization.

v2 API - 图97400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图98401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图99404

Not found. InfluxDB can’t find the organization.

v2 API - 图100500

Internal server error. The server encountered an unexpected situation.

v2 API - 图101default

Unexpected error

get/api/v2/orgs/{orgID}/membersv2 API - 图102

/api/v2/orgs/{orgID}/members

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from an organization

Removes a member from an organization.

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

InfluxDB Cloud

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

204

Success. The user is no longer a member of the organization.

v2 API - 图103401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图104404

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

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

v2 API - 图105500

Internal server error. The server encountered an unexpected situation.

v2 API - 图106default

Unexpected error

delete/api/v2/orgs/{orgID}/members/{userID}v2 API - 图107

/api/v2/orgs/{orgID}/members/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图108200

A list of organization owners

v2 API - 图109404

Organization not found

v2 API - 图110default

Unexpected error

get/api/v2/orgs/{orgID}/ownersv2 API - 图111

/api/v2/orgs/{orgID}/owners

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove an owner from an organization

Removes an owner from the organization.

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

InfluxDB Cloud

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

204

Success. The user is no longer an owner of the organization.

v2 API - 图112401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图113404

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

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

v2 API - 图114500

Internal server error. The server encountered an unexpected situation.

v2 API - 图115default

Unexpected error

delete/api/v2/orgs/{orgID}/owners/{userID}v2 API - 图116

/api/v2/orgs/{orgID}/owners/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图117200

A list of all secret keys

v2 API - 图118default

Unexpected error

get/api/v2/orgs/{orgID}/secretsv2 API - 图119

/api/v2/orgs/{orgID}/secrets

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a secret from an organization

Authorizations:

TokenAuthentication

path Parameters
orgID
required
string

The organization ID.

secretID
required
string

The secret ID.

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

OpenTracing span context

Responses

204

Keys successfully deleted

v2 API - 图120default

Non 2XX error response from server.

delete/api/v2/orgs/{orgID}/secrets/{secretID}v2 API - 图121

/api/v2/orgs/{orgID}/secrets/{secretID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Keys successfully patched

v2 API - 图122default

Unexpected error

post/api/v2/orgs/{orgID}/secrets/deletev2 API - 图123

/api/v2/orgs/{orgID}/secrets/delete

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "secrets": [ - "string" ] }

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Success. The user is authenticated. The Set-Cookie response header contains the session cookie.

v2 API - 图124401

Unauthorized. This error may be caused by one of the following problems:

  • The user doesn’t have access.
  • The user passed incorrect credentials in the request.
  • The credentials are formatted incorrectly in the request.

v2 API - 图125403

Forbidden. The user account is disabled.

v2 API - 图126default

Unsuccessful authentication.

post/api/v2/signinv2 API - 图127

/api/v2/signin

Request samples

  • cURL: signin with —user option encoding

Copy

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

Response samples

  • 401
  • 403
  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Success. The session is expired.

v2 API - 图128401

Unauthorized.

v2 API - 图129default

The session expiry is unsuccessful.

post/api/v2/signoutv2 API - 图130

/api/v2/signout

Request samples

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

Copy

  1. # The following example shows how to use cURL and the InfluxDB API
  2. # to do the following:
  3. # 1. Sign in a user with a username and password.
  4. # 2. Check that the user session exists for the user.
  5. # 3. Sign out the user to expire the session.
  6. # 4. Check that the session is no longer active.
  8. # 1. Send a request to `POST /api/v2/signin` to sign in the user.
  9. #    In your request, pass the following:
  10. #
  11. #      - `--user` option with basic authentication credentials.
  12. #      - `-c` option with a file path where cURL will write cookies.
  14.       curl --request POST \
  15.         -c ./cookie-file.tmp \
  16.         "$INFLUX_URL/api/v2/signin" \
  17.         --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}"
  19. # 2. To check that a user session exists for the user in step 1,
  20. #    send a request to `GET /api/v2/me`.
  21. #    In your request, pass the `-b` option with the session cookie file path from step 1.
  23.       curl --request GET \
  24.         -b ./cookie-file.tmp \
  25.         "$INFLUX_URL/api/v2/me"
  27. #    InfluxDB responds with the `user` resource.
  29. # 3. Send a request to `POST /api/v2/signout` to expire the user session.
  30. #    In your request, pass the `-b` option with the session cookie file path from step 1.
  32.       curl --request POST \
  33.         -b ./cookie-file.tmp \
  34.         "$INFLUX_URL/api/v2/signout"
  36. #     If the user session is successfully expired, InfluxDB responds with
  37.       an HTTP `204` status code.
  39. # 4. To check that the user session is expired, call `GET /api/v2/me` again,
  40. #    passing the `-b` option with the cookie file path.
  42.       curl --request GET \
  43.         -b ./cookie-file.tmp \
  44.         "$INFLUX_URL/api/v2/me"
  46. #    If the user session is expired, InfluxDB responds with an HTTP `401` status code.

Response samples

  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List users

Lists users. Default limit is 20.

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

Required permissions for InfluxDB OSS

ActionPermission requiredRestriction
List all usersOperator token
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
after
string

A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record.

Use after instead of the offset parameter. For more information about pagination parameters, see Pagination.

id
string

A user ID. Only lists the specified user.

limit
integer [ 1 .. 100 ]
Default: 20

Limits the number of records returned. Default is 20.

name
string

A user name. Only lists the specified user.

offset
integer >= 0

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

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

OpenTracing span context

Responses

v2 API - 图131200

Success. The response contains a list of users.

v2 API - 图132401

Unauthorized.

v2 API - 图133422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图134500

Internal server error. The server encountered an unexpected situation.

v2 API - 图135default

Non 2XX error response from server.

get/api/v2/usersv2 API - 图136

/api/v2/users

Response samples

  • 200
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

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

v2 API - 图137200

Success. The response body contains the user.

v2 API - 图138default

Non 2XX error response from server.

get/api/v2/users/{userID}v2 API - 图139

/api/v2/users/{userID}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a password

Updates a user password.

InfluxDB Cloud

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

TokenAuthentication

path Parameters
userID
required
string

The ID of the user to set the password for.

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

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password
required
string

Responses

204

Success. The password is updated.

v2 API - 图140400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS

  • Doesn’t understand a value passed in the request.

v2 API - 图141default

Non 2XX error response from server.

post/api/v2/users/{userID}/passwordv2 API - 图142

/api/v2/users/{userID}/password

Request samples

  • Payload
  • cURL: use HTTP POST to update the user password

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Success. The password is updated.

v2 API - 图143400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS

  • Doesn’t understand a value passed in the request.

v2 API - 图144default

Non 2XX error response from server.

put/api/v2/users/{userID}/passwordv2 API - 图145

/api/v2/users/{userID}/password

Request samples

  • Payload
  • cURL: use Basic auth to update the user password

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图146200

Success. The response body contains key-value pairs with the resource name and top-level route.

get/api/v2v2 API - 图147

/api/v2

Response samples

  • 200

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve runtime configuration

Returns the active runtime configuration of the InfluxDB instance.

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图148200

Success. The response body contains the active runtime configuration of the InfluxDB instance.

v2 API - 图149401

Non 2XX error response from server.

v2 API - 图150default

Non 2XX error response from server.

get/api/v2/configv2 API - 图151

/api/v2/config

Response samples

  • 200
  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "config": { } }

Retrieve all runtime profiles

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

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

TokenAuthentication

query Parameters
cpu
string <duration>

Collects and returns CPU profiling data for the specified duration.

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

OpenTracing span context

Responses

v2 API - 图152200

Go runtime profile reports.

v2 API - 图153default

Non 2XX error response from server.

get/debug/pprof/allv2 API - 图154

/debug/pprof/all

Request samples

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

Copy

  1. # Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.
  3. curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz
  5. # x profiles/cpu.pb.gz
  6. # x profiles/goroutine.pb.gz
  7. # x profiles/block.pb.gz
  8. # x profiles/mutex.pb.gz
  9. # x profiles/heap.pb.gz
  10. # x profiles/allocs.pb.gz
  11. # x profiles/threadcreate.pb.gz
  13. # Analyze a profile.
  15. go tool pprof profiles/heap.pb.gz

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the memory allocations runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图155200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图156default

Non 2XX error response from server.

get/debug/pprof/allocsv2 API - 图157

/debug/pprof/allocs

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/allocs
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. # At the prompt, get the top N memory allocations.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the block runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图158200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图159default

Non 2XX error response from server.

get/debug/pprof/blockv2 API - 图160

/debug/pprof/block

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/block
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the command line invocation

Returns the command line that invoked InfluxDB.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图161200

Command line invocation.

v2 API - 图162default

Non 2XX error response from server.

get/debug/pprof/cmdlinev2 API - 图163

/debug/pprof/cmdline

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the goroutines runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as
    1.  human-readable text with comments that translate addresses to
    2.  function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图164200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图165default

Non 2XX error response from server.

get/debug/pprof/goroutinev2 API - 图166

/debug/pprof/goroutine

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/goroutine
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the heap runtime profile

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

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

gc
integer <int64>
Enum: 0 1
  • 0: (Default) don’t force garbage collection before sampling.
  • 1: Force garbage collection before sampling.
seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图167200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图168default

Non 2XX error response from server.

get/debug/pprof/heapv2 API - 图169

/debug/pprof/heap

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/heap
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. # At the prompt, get the top N memory-intensive nodes.
  11. (pprof) top10
  13. # pprof displays the list:
  14. #   Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total
  15. #   Dropped 895 nodes (cum <= 0.83MB)
  16. #   Showing top 10 nodes out of 143

Response samples

  • 200
  • default

Content type

application/octet-stream

v2 API - 图170

application/octet-stream

text/plain

No sample

Retrieve the mutual exclusion (mutex) runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图171200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图172default

Non 2XX error response from server.

get/debug/pprof/mutexv2 API - 图173

/debug/pprof/mutex

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/mutex
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the CPU runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
seconds
string <int64>

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

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

OpenTracing span context

Responses

v2 API - 图174200

Go runtime profile report compatible with pprof analysis and visualization tools.

v2 API - 图175default

Non 2XX error response from server.

get/debug/pprof/profilev2 API - 图176

/debug/pprof/profile

Request samples

  • Shell: go tool pprof

Copy

  1. # Download the profile report.
  3. curl http://localhost:8086/debug/pprof/profile -o cpu
  5. # Analyze the profile in interactive mode.
  7. go tool pprof ./cpu
  9. # At the prompt, get the top N functions most often running
  10. # or waiting during the sample period.
  12. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the threadcreate runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图177200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图178default

Non 2XX error response from server.

get/debug/pprof/threadcreatev2 API - 图179

/debug/pprof/threadcreate

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/threadcreate
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • 200
  • default

Content type

application/octet-stream

v2 API - 图180

application/octet-stream

text/plain

No sample

Retrieve the runtime execution trace

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

Authorizations:

TokenAuthentication

query Parameters
seconds
string <int64>

Number of seconds to collect profile data.

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

OpenTracing span context

Responses

v2 API - 图181200

Trace file compatible with the Golang trace command.

v2 API - 图182default

Non 2XX error response from server.

get/debug/pprof/tracev2 API - 图183

/debug/pprof/trace

Request samples

  • Shell: go tool trace

Copy

  1. # Download the trace file.
  3. curl http://localhost:8086/debug/pprof/trace -o trace
  5. # Analyze the trace.
  7. go tool trace ./trace

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the health of the instance

Returns the health of the instance.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图184200

The instance is healthy. The response body contains the health check items and status.

v2 API - 图185503

The instance is unhealthy.

v2 API - 图186default

Non 2XX error response from server.

get/healthv2 API - 图187

/health

Response samples

  • 200
  • 503
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve workload performance metrics

Returns metrics about the workload performance of an InfluxDB instance.

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图188200

Success. The response body contains metrics in Prometheus plain-text exposition format Metrics contain a name, an optional set of key-value pairs, and a value.

The following descriptors precede each metric:

v2 API - 图189default

Non 2XX error response from server.

get/metricsv2 API - 图190

/metrics

Response samples

  • 200
  • default

Content type

text/plain

Copy

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

Get the status of the instance

Retrieves the status and InfluxDB version of the instance.

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

InfluxDB Cloud

  • Isn’t versioned and doesn’t return X-Influxdb-Version in the headers.
Authorizations:

TokenAuthentication

Responses

v2 API - 图191204

Success. Headers contain InfluxDB version information.

get/pingv2 API - 图192

/ping

Request samples

  • cURL

Copy

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

Get the readiness of an instance at startup

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图193200

The instance is ready

v2 API - 图194default

Non 2XX error response from server.

get/readyv2 API - 图195

/ready

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all known resources

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图196200

All resources targets

v2 API - 图197default

Internal server error

get/api/v2/resourcesv2 API - 图198

/api/v2/resources

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

[ - "string" ]

)Authorizations (API tokens)

Create and manage authorizations (API tokens).

An authorization contains a list of read and write permissions for organization resources and provides an API token for authentication. An authorization belongs to an organization and only contains permissions for that organization.

We recommend creating a generic user to create and manage tokens for writing data.

User sessions with authorizations

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

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

v2 API - 图199200

Success. The response body contains a list of authorizations.

If the response body is missing authorizations that you expect, check that the API token used in the request has read-user permission for the users (userID property value) in those authorizations.

InfluxDB OSS

  • Warning: The response body contains authorizations with their API token values in clear text.
  • If the request uses an operator token, InfluxDB OSS returns authorizations for all organizations in the instance.

v2 API - 图200400

Non 2XX error response from server.

v2 API - 图201401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图202500

Internal server error. The server encountered an unexpected situation.

v2 API - 图203default

Non 2XX error response from server.

get/api/v2/authorizationsv2 API - 图204

/api/v2/authorizations

Response samples

  • 200
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create an authorization

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

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

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

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

We recommend the following for managing your tokens:

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

Required permissions

  • write-authorizations
  • write-user for the user that the authorization is scoped to
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

v2 API - 图206201

Success. The authorization is created. The response body contains the authorization.

v2 API - 图207400

Non 2XX error response from server.

v2 API - 图208401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图209500

Internal server error. The server encountered an unexpected situation.

v2 API - 图210default

Non 2XX error response from server.

post/api/v2/authorizationsv2 API - 图211

/api/v2/authorizations

Request samples

  • Payload

Content type

application/json

Example

An authorization for a resource type

v2 API - 图212

An authorization for a resource type

An authorization for a resource

An authorization scoped to a user

Creates an authorization.

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete an authorization

Deletes an authorization.

Use the endpoint to delete an API token.

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

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

An authorization ID. Specifies the authorization to delete.

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

OpenTracing span context

Responses

204

Success. The authorization is deleted.

v2 API - 图213400

Bad request.

v2 API - 图214401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图215404

Not found.

v2 API - 图216500

Internal server error. The server encountered an unexpected situation.

v2 API - 图217default

Non 2XX error response from server.

delete/api/v2/authorizations/{authID}v2 API - 图218

/api/v2/authorizations/{authID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图219200

Success. The response body contains the authorization.

v2 API - 图220400

Bad request.

v2 API - 图221401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图222404

Not found.

v2 API - 图223500

Internal server error. The server encountered an unexpected situation.

v2 API - 图224default

Non 2XX error response from server.

get/api/v2/authorizations/{authID}v2 API - 图225

/api/v2/authorizations/{authID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update an API token to be active or inactive

Updates an authorization.

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

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

An authorization ID. Specifies the authorization to update.

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

OpenTracing span context

Request Body schema: application/json

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

description
string

A description of the token.

status
string
Default: “active”
Enum: “active” “inactive”

Status of the token. If inactive, InfluxDB rejects requests that use the token.

Responses

v2 API - 图226200

Success. The response body contains the updated authorization.

v2 API - 图227default

Non 2XX error response from server.

patch/api/v2/authorizations/{authID}v2 API - 图228

/api/v2/authorizations/{authID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Backup

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

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图229200

Success. The response contains a snapshot of KV metadata.

v2 API - 图230default

Non 2XX error response from server.

get/api/v2/backup/kvv2 API - 图231

/api/v2/backup/kv

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Download snapshot of all metadata in the server

Authorizations:

TokenAuthentication

header Parameters
Accept-Encoding
string
Default: identity
Enum: “gzip” “identity”

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

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

OpenTracing span context

Responses

v2 API - 图232200

Snapshot of metadata

v2 API - 图233default

Non 2XX error response from server.

get/api/v2/backup/metadatav2 API - 图234

/api/v2/backup/metadata

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Download snapshot of all TSM data in a shard

Authorizations:

TokenAuthentication

path Parameters
shardID
required
integer <int64>

The shard ID.

query Parameters
since
string <date-time>
Examples:
  • since=2006-01-02T15:04:05Z07:00 - RFC3339 date/time format

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

header Parameters
Accept-Encoding
string
Default: identity
Enum: “gzip” “identity”

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

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

OpenTracing span context

Responses

v2 API - 图235200

TSM snapshot.

v2 API - 图236404

Shard not found.

v2 API - 图237default

Non 2XX error response from server.

get/api/v2/backup/shards/{shardID}v2 API - 图238

/api/v2/backup/shards/{shardID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Buckets

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

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

v2 API - 图239200

Success. The response body contains a list of buckets.

v2 API - 图240401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图241500

Internal server error. The server encountered an unexpected situation.

v2 API - 图242default

Unexpected error

get/api/v2/bucketsv2 API - 图243

/api/v2/buckets

Request samples

  • cURL: filter buckets by name

Copy

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

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create a bucket

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

InfluxDB OSS

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

Limitations

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

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

The bucket to create.

description
string

A description of the bucket.

name
required
string

The bucket name.

orgID
required
string

The organization ID. Specifies the organization that owns the bucket.

Array of objects (RetentionRules)

Retention rules to expire or retain data. The InfluxDB /api/v2 API uses RetentionRules to configure the retention period.

InfluxDB Cloud

  • retentionRules is required.

InfluxDB OSS

  • retentionRules isn’t required.
rp
string
Default: “0”

The retention policy for the bucket. For InfluxDB 1.x, specifies the duration of time that each data point in the retention policy persists.

If you need compatibility with InfluxDB 1.x, specify a value for the rp property; otherwise, see the retentionRules property.

Retention policy is an InfluxDB 1.x concept. The InfluxDB 2.x and Cloud equivalent is retention period. The InfluxDB /api/v2 API uses RetentionRules to configure the retention period.

schemaType
string (SchemaType)
Enum: “implicit” “explicit”

Responses

v2 API - 图245201

Success. The bucket is created.

v2 API - 图246400

Bad request.

v2 API - 图247401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图248403

Forbidden. The bucket quota is exceeded.

v2 API - 图249422

Unprocessable Entity. The request body failed validation.

v2 API - 图250500

Internal server error. The server encountered an unexpected situation.

v2 API - 图251default

Unexpected error

post/api/v2/bucketsv2 API - 图252

/api/v2/buckets

Request samples

  • Payload
  • cURL: create a bucket with retention period
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 403
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a bucket

Deletes a bucket and all associated records.

InfluxDB Cloud

  • Does the following when you send a delete request:

    1. Validates the request and queues the delete.
    2. Returns an HTTP 204 status code if queued; error otherwise.
    3. Handles the delete asynchronously.

InfluxDB OSS

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

Limitations

  • Only one bucket can be deleted per request.
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

204

Success.

InfluxDB Cloud

  • The bucket is queued for deletion.

InfluxDB OSS

  • The bucket is deleted.

v2 API - 图253400

Bad Request.

v2 API - 图254401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图255404

Not found. Bucket not found.

v2 API - 图256500

Internal server error. The server encountered an unexpected situation.

v2 API - 图257default

Unexpected error

delete/api/v2/buckets/{bucketID}v2 API - 图258

/api/v2/buckets/{bucketID}

Request samples

  • cURL

Copy

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

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图259200

Success. The response body contains the bucket information.

v2 API - 图260401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图261404

Not found. Bucket not found.

v2 API - 图262500

Internal server error. The server encountered an unexpected situation.

v2 API - 图263default

Unexpected error

get/api/v2/buckets/{bucketID}v2 API - 图264

/api/v2/buckets/{bucketID}

Response samples

  • 200
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a bucket

Updates a bucket.

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

InfluxDB Cloud

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

InfluxDB OSS

  • Doesn’t require retentionRules.
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

v2 API - 图266200

An updated bucket

v2 API - 图267400

Bad Request.

v2 API - 图268401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图269403

Forbidden.

v2 API - 图270404

Not found. Bucket not found.

v2 API - 图271500

Internal server error. The server encountered an unexpected situation.

v2 API - 图272default

Unexpected error

patch/api/v2/buckets/{bucketID}v2 API - 图273

/api/v2/buckets/{bucketID}

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • 401
  • 403
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all labels for a bucket

Lists all labels for a bucket.

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

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

v2 API - 图274200

Success. The response body contains a list of all labels for the bucket.

v2 API - 图275400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图276401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图277404

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

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

v2 API - 图278500

Internal server error. The server encountered an unexpected situation.

v2 API - 图279default

Unexpected error

get/api/v2/buckets/{bucketID}/labelsv2 API - 图280

/api/v2/buckets/{bucketID}/labels

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a bucket

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

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

Limitations

  • Before adding a label to a bucket, you must create the label if you haven’t already. To create a label with the InfluxDB API, send a POST request to the /api/v2/labels endpoint).
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

v2 API - 图281201

Success. The response body contains the label information.

v2 API - 图282400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图283401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图284404

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

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

v2 API - 图285422

Unprocessable entity. Label already exists on the resource.

v2 API - 图286500

Internal server error. The server encountered an unexpected situation.

v2 API - 图287default

Unexpected error

post/api/v2/buckets/{bucketID}/labelsv2 API - 图288

/api/v2/buckets/{bucketID}/labels

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • 400
  • 401
  • 404
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label from a bucket

Authorizations:

TokenAuthentication

path Parameters
bucketID
required
string

The bucket ID.

labelID
required
string

The ID of the label to delete.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图289404

Bucket not found

v2 API - 图290default

Unexpected error

delete/api/v2/buckets/{bucketID}/labels/{labelID}v2 API - 图291

/api/v2/buckets/{bucketID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图292200

Success. The response body contains a list of all users for the bucket.

v2 API - 图293400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图294401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图295404

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

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

v2 API - 图296500

Internal server error. The server encountered an unexpected situation.

v2 API - 图297default

Unexpected error

get/api/v2/buckets/{bucketID}/membersv2 API - 图298

/api/v2/buckets/{bucketID}/members

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a member to a bucket

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

InfluxDB users have permission to access InfluxDB.

Members are users in an organization.

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

Authorizations:

TokenAuthentication

path Parameters
bucketID
required
string

The ID of the bucket to retrieve users for.

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

OpenTracing span context

Request Body schema: application/json

A user to add as a member to the bucket.

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图299201

Success. The response body contains the user information.

v2 API - 图300400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图301401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图302404

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

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

v2 API - 图303500

Internal server error. The server encountered an unexpected situation.

v2 API - 图304default

Unexpected error

post/api/v2/buckets/{bucketID}/membersv2 API - 图305

/api/v2/buckets/{bucketID}/members

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from a bucket

Removes a member from a bucket.

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

Authorizations:

TokenAuthentication

path Parameters
bucketID
required
string

The ID of the bucket to remove a user from.

userID
required
string

The ID of the user to remove.

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

OpenTracing span context

Responses

204

Success. The user is no longer a member of the bucket.

v2 API - 图306401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图307404

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

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

v2 API - 图308500

Internal server error. The server encountered an unexpected situation.

v2 API - 图309default

Unexpected error

delete/api/v2/buckets/{bucketID}/members/{userID}v2 API - 图310

/api/v2/buckets/{bucketID}/members/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图311200

Success. The response body contains a list of all owners for the bucket.

v2 API - 图312400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图313401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图314404

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

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

v2 API - 图315500

Internal server error. The server encountered an unexpected situation.

v2 API - 图316default

Unexpected error

get/api/v2/buckets/{bucketID}/ownersv2 API - 图317

/api/v2/buckets/{bucketID}/owners

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add an owner to a bucket

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

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

InfluxDB Cloud

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

v2 API - 图318201

Created. The bucket owner role is assigned to the user. The response body contains the resource owner with role and user detail.

v2 API - 图319400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图320401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图321404

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

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

v2 API - 图322500

Internal server error. The server encountered an unexpected situation.

v2 API - 图323default

Unexpected error

post/api/v2/buckets/{bucketID}/ownersv2 API - 图324

/api/v2/buckets/{bucketID}/owners

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove an owner from a bucket

Removes an owner from a bucket.

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

InfluxDB Cloud

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

204

Success. The user is no longer an owner of the bucket.

v2 API - 图325401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图326404

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

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

v2 API - 图327500

Internal server error. The server encountered an unexpected situation.

v2 API - 图328default

Unexpected error

delete/api/v2/buckets/{bucketID}/owners/{userID}v2 API - 图329

/api/v2/buckets/{bucketID}/owners/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Get buckets in a source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

query Parameters
org
string

The name of the organization.

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

OpenTracing span context

Responses

v2 API - 图330200

A source

v2 API - 图331404

Source not found

v2 API - 图332default

Unexpected error

get/api/v2/sources/{sourceID}/bucketsv2 API - 图333

/api/v2/sources/{sourceID}/buckets

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Cells

Create a dashboard cell

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json

Cell that will be added

h
integer <int32>
name
string
usingView
string

Makes a copy of the provided view.

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

Responses

v2 API - 图334201

Cell successfully added

v2 API - 图335404

Dashboard not found

v2 API - 图336default

Unexpected error

post/api/v2/dashboards/{dashboardID}/cellsv2 API - 图337

/api/v2/dashboards/{dashboardID}/cells

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Replace cells in a dashboard

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

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json

Array ()

h
integer <int32>
id
string
object
viewID
string

The reference to a view from the views API.

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

Responses

v2 API - 图339201

Replaced dashboard cells

v2 API - 图340404

Dashboard not found

v2 API - 图341default

Unexpected error

put/api/v2/dashboards/{dashboardID}/cellsv2 API - 图342

/api/v2/dashboards/{dashboardID}/cells

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a dashboard cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The ID of the cell to delete.

dashboardID
required
string

The ID of the dashboard to delete.

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

OpenTracing span context

Responses

204

Cell successfully deleted

v2 API - 图343404

Cell or dashboard not found

v2 API - 图344default

Unexpected error

delete/api/v2/dashboards/{dashboardID}/cells/{cellID}v2 API - 图345

/api/v2/dashboards/{dashboardID}/cells/{cellID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

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

v2 API - 图346200

Updated dashboard cell

v2 API - 图347404

Cell or dashboard not found

v2 API - 图348default

Unexpected error

patch/api/v2/dashboards/{dashboardID}/cells/{cellID}v2 API - 图349

/api/v2/dashboards/{dashboardID}/cells/{cellID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the view for a cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The cell ID.

dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Responses

v2 API - 图350200

A dashboard cells view

v2 API - 图351404

Cell or dashboard not found

v2 API - 图352default

Unexpected error

get/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图353

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The ID of the cell to update.

dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json
name
required
string
required
LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

v2 API - 图355200

Updated cell view

v2 API - 图356404

Cell or dashboard not found

v2 API - 图357default

Unexpected error

patch/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图358

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Checks

List all checks

Authorizations:

TokenAuthentication

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Limits the number of records returned. Default is 20.

offset
integer >= 0

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

orgID
required
string

Only show checks that belong to a specific organization ID.

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

OpenTracing span context

Responses

v2 API - 图359200

A list of checks

v2 API - 图360default

Unexpected error

get/api/v2/checksv2 API - 图361

/api/v2/checks

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add new check

Authorizations:

TokenAuthentication

Request Body schema: application/json

Check to create

description
string

An optional description of the check.

Array of objects (Labels)
name
required
string
orgID
required
string

The ID of the organization that owns this check.

required
object (DashboardQuery)
status
string (TaskStatusType)
Enum: “active” “inactive”

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

taskID
string

The ID of the task associated with this check.

type
required
string
custom
v2 API - 图364
PostCheck
Check
threshold
deadman
custom

Responses

v2 API - 图365201

Check created

v2 API - 图366default

Unexpected error

post/api/v2/checksv2 API - 图367

/api/v2/checks

Request samples

  • Payload

Content type

application/json

Example

custom

v2 API - 图368

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Example

custom

v2 API - 图369

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

Delete a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图370404

The check was not found

v2 API - 图371default

Unexpected error

delete/api/v2/checks/{checkID}v2 API - 图372

/api/v2/checks/{checkID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图373200

The check requested

v2 API - 图374default

Unexpected error

get/api/v2/checks/{checkID}v2 API - 图375

/api/v2/checks/{checkID}

Response samples

  • 200
  • default

Content type

application/json

Example

custom

v2 API - 图376

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

Update a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

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

OpenTracing span context

Request Body schema: application/json

Check update to apply

description
string
name
string
status
string
Enum: “active” “inactive”

Responses

v2 API - 图377200

An updated check

v2 API - 图378404

The check was not found

v2 API - 图379default

Unexpected error

patch/api/v2/checks/{checkID}v2 API - 图380

/api/v2/checks/{checkID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

custom

v2 API - 图381

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

Update a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

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

OpenTracing span context

Request Body schema: application/json

Check update to apply

description
string

An optional description of the check.

Array of objects (Labels)
name
required
string
orgID
required
string

The ID of the organization that owns this check.

required
object (DashboardQuery)
status
string (TaskStatusType)
Enum: “active” “inactive”

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

taskID
string

The ID of the task associated with this check.

type
required
string
custom
v2 API - 图384
PostCheck
Check
threshold
deadman
custom

Responses

v2 API - 图385200

An updated check

v2 API - 图386404

The check was not found

v2 API - 图387default

Unexpected error

put/api/v2/checks/{checkID}v2 API - 图388

/api/v2/checks/{checkID}

Request samples

  • Payload

Content type

application/json

Example

custom

v2 API - 图389

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

custom

v2 API - 图390

custom

deadman

threshold

Check

PostCheck

Copy

Expand all Collapse all

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

List all labels for a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

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

OpenTracing span context

Responses

v2 API - 图391200

A list of all labels for a check

v2 API - 图392default

Unexpected error

get/api/v2/checks/{checkID}/labelsv2 API - 图393

/api/v2/checks/{checkID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

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

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图394201

The label was added to the check

v2 API - 图395default

Unexpected error

post/api/v2/checks/{checkID}/labelsv2 API - 图396

/api/v2/checks/{checkID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete label from a check

Authorizations:

TokenAuthentication

path Parameters
checkID
required
string

The check ID.

labelID
required
string

The ID of the label to delete.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图397404

Check or label not found

v2 API - 图398default

Unexpected error

delete/api/v2/checks/{checkID}/labels/{labelID}v2 API - 图399

/api/v2/checks/{checkID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图400200

The check query requested

v2 API - 图401400

Invalid request

v2 API - 图402404

Check not found

v2 API - 图403default

Unexpected error

get/api/v2/checks/{checkID}/queryv2 API - 图404

/api/v2/checks/{checkID}/query

Response samples

  • 200
  • 400
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "flux": "string" }

Config

Retrieve runtime configuration

Returns the active runtime configuration of the InfluxDB instance.

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图405200

Success. The response body contains the active runtime configuration of the InfluxDB instance.

v2 API - 图406401

Non 2XX error response from server.

v2 API - 图407default

Non 2XX error response from server.

get/api/v2/configv2 API - 图408

/api/v2/config

Response samples

  • 200
  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图409200

Success. The response body contains feature flags.

v2 API - 图410401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图411500

Internal server error. The server encountered an unexpected situation.

v2 API - 图412default

Unexpected error

get/api/v2/flagsv2 API - 图413

/api/v2/flags

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ }

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

Limits the number of records returned. Default is 20.

offset
integer >= 0

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

org
string

An organization name. Only returns dashboards that belong to the specified organization.

orgID
string

An organization ID. Only returns dashboards that belong to the specified organization.

owner
string

A user ID. Only returns dashboards where the specified user has the owner role.

sortBy
string
Enum: “ID” “CreatedAt” “UpdatedAt”

The column to sort by.

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

OpenTracing span context

Responses

v2 API - 图414200

Success. The response body contains dashboards.

v2 API - 图415default

Unexpected error

get/api/v2/dashboardsv2 API - 图416

/api/v2/dashboards

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create a dashboard

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

Dashboard to create

description
string

The user-facing description of the dashboard.

name
required
string

The user-facing name of the dashboard.

orgID
required
string

The ID of the organization that owns the dashboard.

Responses

v2 API - 图417201

Success. The dashboard is created.

v2 API - 图418default

Unexpected error

post/api/v2/dashboardsv2 API - 图419

/api/v2/dashboards

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Example

Dashboard

v2 API - 图420

Dashboard

DashboardWithViewProperties

Copy

Expand all Collapse all

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

Delete a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图421404

Dashboard not found

v2 API - 图422default

Unexpected error

delete/api/v2/dashboards/{dashboardID}v2 API - 图423

/api/v2/dashboards/{dashboardID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图424200

Retrieve a single dashboard

v2 API - 图425404

Dashboard not found

v2 API - 图426default

Unexpected error

get/api/v2/dashboards/{dashboardID}v2 API - 图427

/api/v2/dashboards/{dashboardID}

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

Dashboard

v2 API - 图428

Dashboard

DashboardWithViewProperties

Copy

Expand all Collapse all

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

Update a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json

Patching of a dashboard

object (schemas)
description
string

optional, when provided will replace the description

name
string

optional, when provided will replace the name

Responses

v2 API - 图430200

Updated dashboard

v2 API - 图431404

Dashboard not found

v2 API - 图432default

Unexpected error

patch/api/v2/dashboards/{dashboardID}v2 API - 图433

/api/v2/dashboards/{dashboardID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create a dashboard cell

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json

Cell that will be added

h
integer <int32>
name
string
usingView
string

Makes a copy of the provided view.

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

Responses

v2 API - 图434201

Cell successfully added

v2 API - 图435404

Dashboard not found

v2 API - 图436default

Unexpected error

post/api/v2/dashboards/{dashboardID}/cellsv2 API - 图437

/api/v2/dashboards/{dashboardID}/cells

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Replace cells in a dashboard

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

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json

Array ()

h
integer <int32>
id
string
object
viewID
string

The reference to a view from the views API.

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

Responses

v2 API - 图439201

Replaced dashboard cells

v2 API - 图440404

Dashboard not found

v2 API - 图441default

Unexpected error

put/api/v2/dashboards/{dashboardID}/cellsv2 API - 图442

/api/v2/dashboards/{dashboardID}/cells

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a dashboard cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The ID of the cell to delete.

dashboardID
required
string

The ID of the dashboard to delete.

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

OpenTracing span context

Responses

204

Cell successfully deleted

v2 API - 图443404

Cell or dashboard not found

v2 API - 图444default

Unexpected error

delete/api/v2/dashboards/{dashboardID}/cells/{cellID}v2 API - 图445

/api/v2/dashboards/{dashboardID}/cells/{cellID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

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

v2 API - 图446200

Updated dashboard cell

v2 API - 图447404

Cell or dashboard not found

v2 API - 图448default

Unexpected error

patch/api/v2/dashboards/{dashboardID}/cells/{cellID}v2 API - 图449

/api/v2/dashboards/{dashboardID}/cells/{cellID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the view for a cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The cell ID.

dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Responses

v2 API - 图450200

A dashboard cells view

v2 API - 图451404

Cell or dashboard not found

v2 API - 图452default

Unexpected error

get/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图453

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The ID of the cell to update.

dashboardID
required
string

The ID of the dashboard to update.

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

OpenTracing span context

Request Body schema: application/json
name
required
string
required
LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

v2 API - 图455200

Updated cell view

v2 API - 图456404

Cell or dashboard not found

v2 API - 图457default

Unexpected error

patch/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图458

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all labels for a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Responses

v2 API - 图459200

A list of all labels for a dashboard

v2 API - 图460default

Unexpected error

get/api/v2/dashboards/{dashboardID}/labelsv2 API - 图461

/api/v2/dashboards/{dashboardID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图462201

The label added to the dashboard

v2 API - 图463default

Unexpected error

post/api/v2/dashboards/{dashboardID}/labelsv2 API - 图464

/api/v2/dashboards/{dashboardID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label from a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

labelID
required
string

The ID of the label to delete.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图465404

Dashboard not found

v2 API - 图466default

Unexpected error

delete/api/v2/dashboards/{dashboardID}/labels/{labelID}v2 API - 图467

/api/v2/dashboards/{dashboardID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图468200

A list of users who have member privileges for a dashboard

v2 API - 图469default

Unexpected error

get/api/v2/dashboards/{dashboardID}/membersv2 API - 图470

/api/v2/dashboards/{dashboardID}/members

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a member to a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Request Body schema: application/json

User to add as member

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图471201

Added to dashboard members

v2 API - 图472default

Unexpected error

post/api/v2/dashboards/{dashboardID}/membersv2 API - 图473

/api/v2/dashboards/{dashboardID}/members

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

userID
required
string

The ID of the member to remove.

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

OpenTracing span context

Responses

204

Member removed

v2 API - 图474default

Unexpected error

delete/api/v2/dashboards/{dashboardID}/members/{userID}v2 API - 图475

/api/v2/dashboards/{dashboardID}/members/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图476200

A list of users who have owner privileges for a dashboard

v2 API - 图477default

Unexpected error

get/api/v2/dashboards/{dashboardID}/ownersv2 API - 图478

/api/v2/dashboards/{dashboardID}/owners

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add an owner to a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

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

OpenTracing span context

Request Body schema: application/json

User to add as owner

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图479201

Added to dashboard owners

v2 API - 图480default

Unexpected error

post/api/v2/dashboards/{dashboardID}/ownersv2 API - 图481

/api/v2/dashboards/{dashboardID}/owners

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove an owner from a dashboard

Authorizations:

TokenAuthentication

path Parameters
dashboardID
required
string

The dashboard ID.

userID
required
string

The ID of the owner to remove.

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

OpenTracing span context

Responses

204

Owner removed

v2 API - 图482default

Unexpected error

delete/api/v2/dashboards/{dashboardID}/owners/{userID}v2 API - 图483

/api/v2/dashboards/{dashboardID}/owners/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图484200

Success. The response body contains a list of database retention policy mappings.

v2 API - 图485400

Bad request. The request has one or more invalid parameters.

v2 API - 图486401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图487500

Internal server error. The server encountered an unexpected situation.

v2 API - 图488default

Unexpected error

get/api/v2/dbrpsv2 API - 图489

/api/v2/dbrps

Response samples

  • 200
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a database retention policy mapping

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

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

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

v2 API - 图490201

Created. The response body contains the database retention policy mapping.

v2 API - 图491400

Bad request. The mapping in the request has one or more invalid IDs.

v2 API - 图492401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图493404

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

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

v2 API - 图494500

Internal server error. The server encountered an unexpected situation.

v2 API - 图495default

Unexpected error

post/api/v2/dbrpsv2 API - 图496

/api/v2/dbrps

Request samples

  • Payload
  • cURL: create a database retention policy mapping

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Success. The delete is accepted.

v2 API - 图497400

Bad Request. Query parameters contain invalid values.

v2 API - 图498401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图499404

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

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

v2 API - 图500500

Internal server error. The server encountered an unexpected situation.

v2 API - 图501default

Unexpected error

delete/api/v2/dbrps/{dbrpID}v2 API - 图502

/api/v2/dbrps/{dbrpID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

The query parameters contain invalid values.

Copy

Expand all Collapse all

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

v2 API - 图503200

Success. The response body contains the DBRP mapping.

v2 API - 图504400

Bad Request. Query parameters contain invalid values.

v2 API - 图505401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图506404

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

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

v2 API - 图507500

Internal server error. The server encountered an unexpected situation.

v2 API - 图508default

Unexpected error

get/api/v2/dbrps/{dbrpID}v2 API - 图509

/api/v2/dbrps/{dbrpID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a database retention policy mapping

Authorizations:

TokenAuthentication

path Parameters
dbrpID
required
string

A DBRP mapping ID. Specifies the DBRP mapping.

query Parameters
org
string

An organization name. Specifies the organization that owns the DBRP mapping.

orgID
string

An organization ID. Specifies the organization that owns the DBRP mapping.

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

OpenTracing span context

Request Body schema: application/json

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

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

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

v2 API - 图510200

An updated mapping

v2 API - 图511400

Bad Request. Query parameters contain invalid values.

v2 API - 图512401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图513404

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

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

v2 API - 图514500

Internal server error. The server encountered an unexpected situation.

v2 API - 图515default

Unexpected error

patch/api/v2/dbrps/{dbrpID}v2 API - 图516

/api/v2/dbrps/{dbrpID}

Request samples

  • Payload
  • cURL: Update a DBRP mapping

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Debug

Generate profiling and trace reports.

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

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

Retrieve all runtime profiles

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

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

TokenAuthentication

query Parameters
cpu
string <duration>

Collects and returns CPU profiling data for the specified duration.

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

OpenTracing span context

Responses

v2 API - 图517200

Go runtime profile reports.

v2 API - 图518default

Non 2XX error response from server.

get/debug/pprof/allv2 API - 图519

/debug/pprof/all

Request samples

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

Copy

  1. # Download and extract a `tar.gz` of all profiles after 10 seconds of CPU sampling.
  3. curl "http://localhost:8086/debug/pprof/all?cpu=10s" | tar -xz
  5. # x profiles/cpu.pb.gz
  6. # x profiles/goroutine.pb.gz
  7. # x profiles/block.pb.gz
  8. # x profiles/mutex.pb.gz
  9. # x profiles/heap.pb.gz
  10. # x profiles/allocs.pb.gz
  11. # x profiles/threadcreate.pb.gz
  13. # Analyze a profile.
  15. go tool pprof profiles/heap.pb.gz

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the memory allocations runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图520200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图521default

Non 2XX error response from server.

get/debug/pprof/allocsv2 API - 图522

/debug/pprof/allocs

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/allocs
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. # At the prompt, get the top N memory allocations.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the block runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图523200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图524default

Non 2XX error response from server.

get/debug/pprof/blockv2 API - 图525

/debug/pprof/block

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/block
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the command line invocation

Returns the command line that invoked InfluxDB.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图526200

Command line invocation.

v2 API - 图527default

Non 2XX error response from server.

get/debug/pprof/cmdlinev2 API - 图528

/debug/pprof/cmdline

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the goroutines runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as
    1.  human-readable text with comments that translate addresses to
    2.  function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图529200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图530default

Non 2XX error response from server.

get/debug/pprof/goroutinev2 API - 图531

/debug/pprof/goroutine

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/goroutine
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the heap runtime profile

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

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

gc
integer <int64>
Enum: 0 1
  • 0: (Default) don’t force garbage collection before sampling.
  • 1: Force garbage collection before sampling.
seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图532200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图533default

Non 2XX error response from server.

get/debug/pprof/heapv2 API - 图534

/debug/pprof/heap

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/heap
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. # At the prompt, get the top N memory-intensive nodes.
  11. (pprof) top10
  13. # pprof displays the list:
  14. #   Showing nodes accounting for 142.46MB, 85.43% of 166.75MB total
  15. #   Dropped 895 nodes (cum <= 0.83MB)
  16. #   Showing top 10 nodes out of 143

Response samples

  • 200
  • default

Content type

application/octet-stream

v2 API - 图535

application/octet-stream

text/plain

No sample

Retrieve the mutual exclusion (mutex) runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图536200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图537default

Non 2XX error response from server.

get/debug/pprof/mutexv2 API - 图538

/debug/pprof/mutex

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/mutex
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the CPU runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
seconds
string <int64>

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

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

OpenTracing span context

Responses

v2 API - 图539200

Go runtime profile report compatible with pprof analysis and visualization tools.

v2 API - 图540default

Non 2XX error response from server.

get/debug/pprof/profilev2 API - 图541

/debug/pprof/profile

Request samples

  • Shell: go tool pprof

Copy

  1. # Download the profile report.
  3. curl http://localhost:8086/debug/pprof/profile -o cpu
  5. # Analyze the profile in interactive mode.
  7. go tool pprof ./cpu
  9. # At the prompt, get the top N functions most often running
  10. # or waiting during the sample period.
  12. (pprof) top10

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve the threadcreate runtime profile

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

Authorizations:

TokenAuthentication

query Parameters
debug
integer <int64>
Enum: 0 1
  • 0: (Default) Return the report as a gzip-compressed protocol buffer.
  • 1: Return a response body with the report formatted as human-readable text. The report contains comments that translate addresses to function names and line numbers for debugging.

debug=1 is mutually exclusive with the seconds query parameter.

seconds
string <int64>

Number of seconds to collect statistics.

seconds is mutually exclusive with debug=1.

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

OpenTracing span context

Responses

v2 API - 图542200

Go runtime profile report compatible with pprof analysis and visualization tools. If debug is enabled (?debug=1), response body contains a human-readable profile.

v2 API - 图543default

Non 2XX error response from server.

get/debug/pprof/threadcreatev2 API - 图544

/debug/pprof/threadcreate

Request samples

  • Shell: go tool pprof

Copy

  1. # Analyze the profile in interactive mode.
  3. go tool pprof http://localhost:8086/debug/pprof/threadcreate
  5. # `pprof` returns the following prompt:
  6. #   Entering interactive mode (type "help" for commands, "o" for options)
  7. #   (pprof)
  9. #  At the prompt, get the top N entries.
  11. (pprof) top10

Response samples

  • 200
  • default

Content type

application/octet-stream

v2 API - 图545

application/octet-stream

text/plain

No sample

Retrieve the runtime execution trace

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

Authorizations:

TokenAuthentication

query Parameters
seconds
string <int64>

Number of seconds to collect profile data.

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

OpenTracing span context

Responses

v2 API - 图546200

Trace file compatible with the Golang trace command.

v2 API - 图547default

Non 2XX error response from server.

get/debug/pprof/tracev2 API - 图548

/debug/pprof/trace

Request samples

  • Shell: go tool trace

Copy

  1. # Download the trace file.
  3. curl http://localhost:8086/debug/pprof/trace -o trace
  5. # Analyze the trace.
  7. go tool trace ./trace

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete

Delete data from an InfluxDB bucket.

Delete data

Deletes data from a bucket.

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

InfluxDB Cloud

  • Does the following when you send a delete request:

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

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

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

InfluxDB OSS

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

Required permissions

  • write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

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

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

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the delete asynchronously - the deletion might not have completed yet.

An HTTP 2xx status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request.

Because writes are asynchronous, data might not yet be written when you receive the response.

InfluxDB OSS

  • Deleted the data.

v2 API - 图549400

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

InfluxDB OSS

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

v2 API - 图550401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图551404

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

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

v2 API - 图552500

Internal server error. The server encountered an unexpected situation.

v2 API - 图553default

Non 2XX error response from server.

post/api/v2/deletev2 API - 图554

/api/v2/delete

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Health

Retrieve the health of the instance

Returns the health of the instance.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图555200

The instance is healthy. The response body contains the health check items and status.

v2 API - 图556503

The instance is unhealthy.

v2 API - 图557default

Non 2XX error response from server.

get/healthv2 API - 图558

/health

Response samples

  • 200
  • 503
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Labels

List all labels

Authorizations:

TokenAuthentication

query Parameters
orgID
string

The organization ID.

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

OpenTracing span context

Responses

v2 API - 图559200

Success. The response body contains a list of labels.

v2 API - 图560500

Internal server error. The server encountered an unexpected situation.

v2 API - 图561default

Non 2XX error response from server.

get/api/v2/labelsv2 API - 图562

/api/v2/labels

Response samples

  • 200
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create a label

Authorizations:

TokenAuthentication

Request Body schema: application/json

The label to create.

name
required
string
orgID
required
string
object

Key-value pairs associated with this label.

To remove a property, send an update with an empty value (“”) for the key.

Responses

v2 API - 图564201

Success. The label was created.

v2 API - 图565500

Internal server error. The server encountered an unexpected situation.

v2 API - 图566default

Non 2XX error response from server.

post/api/v2/labelsv2 API - 图567

/api/v2/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The ID of the label to delete.

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

OpenTracing span context

Responses

204

Success. The delete was accepted.

v2 API - 图568401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图569404

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

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

v2 API - 图570500

Internal server error. The server encountered an unexpected situation.

v2 API - 图571default

Non 2XX error response from server.

delete/api/v2/labels/{labelID}v2 API - 图572

/api/v2/labels/{labelID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图573200

Success. The response body contains the label.

v2 API - 图574500

Internal server error. The server encountered an unexpected situation.

v2 API - 图575default

Non 2XX error response from server.

get/api/v2/labels/{labelID}v2 API - 图576

/api/v2/labels/{labelID}

Response samples

  • 200
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a label

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The ID of the label to update.

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

OpenTracing span context

Request Body schema: application/json

A label update.

name
string
object

Responses

v2 API - 图578200

Success. The response body contains the updated label.

v2 API - 图579401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图580404

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

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

v2 API - 图581500

Internal server error. The server encountered an unexpected situation.

v2 API - 图582default

Non 2XX error response from server.

patch/api/v2/labels/{labelID}v2 API - 图583

/api/v2/labels/{labelID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Legacy Authorizations

List all legacy authorizations

Authorizations:

TokenAuthentication

query Parameters
authID
string

An authorization ID. Returns the specified legacy authorization.

org
string

An organization name. Only returns legacy authorizations that belong to the specified organization.

orgID
string

An organization ID. Only returns legacy authorizations that belong to the specified organization.

token
string

An authorization name token. Only returns legacy authorizations with the specified name.

user
string

A user name. Only returns legacy authorizations scoped to the specified user.

userID
string

A user ID. Only returns legacy authorizations scoped to the specified user.

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

OpenTracing span context

Responses

v2 API - 图584200

Success. The response body contains a list of legacy authorizations.

v2 API - 图585default

Non 2XX error response from server.

get/legacy/authorizationsv2 API - 图586

/private/legacy/authorizations

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create a legacy authorization

Creates a legacy authorization and returns the legacy authorization.

Required permissions

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

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

The legacy authorization to create.

description
string

A description of the token.

orgID
required
string

The organization ID. Identifies the organization that the authorization is scoped to.

required
Array of objects (Permission) non-empty

The list of permissions that provide read and write access to organization resources. An authorization must contain at least one permission.

status
string
Default: “active”
Enum: “active” “inactive”

Status of the token. If inactive, InfluxDB rejects requests that use the token.

token
string

The name that you provide for the authorization.

userID
string

The user ID. Identifies the user that the authorization is scoped to.

Responses

v2 API - 图588201

Created. The legacy authorization is created. The response body contains the newly created legacy authorization.

v2 API - 图589400

Non 2XX error response from server.

v2 API - 图590401

Unauthorized. The API token passed doesn’t have the permissions necessary for the request.

v2 API - 图591default

Non 2XX error response from server.

post/legacy/authorizationsv2 API - 图592

/private/legacy/authorizations

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a legacy authorization

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

The ID of the legacy authorization to delete.

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

OpenTracing span context

Responses

204

Legacy authorization deleted

v2 API - 图593default

Non 2XX error response from server.

delete/legacy/authorizations/{authID}v2 API - 图594

/private/legacy/authorizations/{authID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图595200

Legacy authorization details

v2 API - 图596default

Non 2XX error response from server.

get/legacy/authorizations/{authID}v2 API - 图597

/private/legacy/authorizations/{authID}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a legacy authorization to be active or inactive

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

The ID of the legacy authorization to update.

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

OpenTracing span context

Request Body schema: application/json

Legacy authorization to update

description
string

A description of the token.

status
string
Default: “active”
Enum: “active” “inactive”

Status of the token. If inactive, InfluxDB rejects requests that use the token.

Responses

v2 API - 图598200

The active or inactive legacy authorization

v2 API - 图599default

Non 2XX error response from server.

patch/legacy/authorizations/{authID}v2 API - 图600

/private/legacy/authorizations/{authID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Set a legacy authorization password

Authorizations:

TokenAuthentication

path Parameters
authID
required
string

The ID of the legacy authorization to update.

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

OpenTracing span context

Request Body schema: application/json

New password

password
required
string

Responses

204

Legacy authorization password set

v2 API - 图601default

Non 2XX error response from server.

post/legacy/authorizations/{authID}/passwordv2 API - 图602

/private/legacy/authorizations/{authID}/password

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图603200

Query results

v2 API - 图604429

InfluxDB Cloud:

  • returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit
  • returns Retry-After header that describes when to try the write again.

InfluxDB OSS:

  • doesn’t return this error.

v2 API - 图605default

Error processing query

get/queryv2 API - 图606

/query

Response samples

  • 200
  • default

Content type

application/csv

v2 API - 图607

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

204

Write data is correctly formatted and accepted for writing to the bucket.

v2 API - 图608400

Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written.

v2 API - 图609401

Token doesn’t have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist.

v2 API - 图610403

No token was sent and they are required.

v2 API - 图611413

Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written.

v2 API - 图612429

Token is temporarily over quota. The Retry-After header describes when to try the write again.

v2 API - 图613503

Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again.

v2 API - 图614default

Internal server error

post/writev2 API - 图615

/write

Response samples

  • 400
  • 401
  • 403
  • 413
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Metrics

Retrieve workload performance metrics

Returns metrics about the workload performance of an InfluxDB instance.

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图616200

Success. The response body contains metrics in Prometheus plain-text exposition format Metrics contain a name, an optional set of key-value pairs, and a value.

The following descriptors precede each metric:

v2 API - 图617default

Non 2XX error response from server.

get/metricsv2 API - 图618

/metrics

Response samples

  • 200
  • default

Content type

text/plain

Copy

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

NotificationEndpoints

List all notification endpoints

Authorizations:

TokenAuthentication

query Parameters
limit
integer [ 1 .. 100 ]
Default: 20

Limits the number of records returned. Default is 20.

offset
integer >= 0

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

orgID
required
string

Only show notification endpoints that belong to specific organization ID.

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

OpenTracing span context

Responses

v2 API - 图619200

A list of notification endpoints

v2 API - 图620default

Unexpected error

get/api/v2/notificationEndpointsv2 API - 图621

/api/v2/notificationEndpoints

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a notification endpoint

Authorizations:

TokenAuthentication

Request Body schema: application/json

Notification endpoint to create

authMethod
required
string
Enum: “none” “basic” “bearer”
contentTemplate
string
description
string

An optional description of the notification endpoint.

object

Customized headers.

id
string
Array of objects (Labels)
method
required
string
Enum: “POST” “GET” “PUT”
name
required
string
orgID
string
password
string
status
string
Default: “active”
Enum: “active” “inactive”

The status of the endpoint.

token
string
type
required
string (NotificationEndpointType)
http
v2 API - 图624
PostNotificationEndpoint
NotificationEndpoint
slack
pagerduty
http
telegram
url
required
string
userID
string
username
string

Responses

v2 API - 图625201

Notification endpoint created

v2 API - 图626default

Unexpected error

post/api/v2/notificationEndpointsv2 API - 图627

/api/v2/notificationEndpoints

Request samples

  • Payload

Content type

application/json

Example

http

v2 API - 图628

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Example

http

v2 API - 图629

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

Delete a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图630404

The endpoint was not found

v2 API - 图631default

Unexpected error

delete/api/v2/notificationEndpoints/{endpointID}v2 API - 图632

/api/v2/notificationEndpoints/{endpointID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图633200

The notification endpoint requested

v2 API - 图634default

Unexpected error

get/api/v2/notificationEndpoints/{endpointID}v2 API - 图635

/api/v2/notificationEndpoints/{endpointID}

Response samples

  • 200
  • default

Content type

application/json

Example

http

v2 API - 图636

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

Update a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

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

OpenTracing span context

Request Body schema: application/json

Check update to apply

description
string
name
string
status
string
Enum: “active” “inactive”

Responses

v2 API - 图637200

An updated notification endpoint

v2 API - 图638404

The notification endpoint was not found

v2 API - 图639default

Unexpected error

patch/api/v2/notificationEndpoints/{endpointID}v2 API - 图640

/api/v2/notificationEndpoints/{endpointID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

http

v2 API - 图641

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

Update a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

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

OpenTracing span context

Request Body schema: application/json

A new notification endpoint to replace the existing endpoint with

authMethod
required
string
Enum: “none” “basic” “bearer”
contentTemplate
string
description
string

An optional description of the notification endpoint.

object

Customized headers.

id
string
Array of objects (Labels)
method
required
string
Enum: “POST” “GET” “PUT”
name
required
string
orgID
string
password
string
status
string
Default: “active”
Enum: “active” “inactive”

The status of the endpoint.

token
string
type
required
string (NotificationEndpointType)
http
v2 API - 图644
PostNotificationEndpoint
NotificationEndpoint
slack
pagerduty
http
telegram
url
required
string
userID
string
username
string

Responses

v2 API - 图645200

An updated notification endpoint

v2 API - 图646404

The notification endpoint was not found

v2 API - 图647default

Unexpected error

put/api/v2/notificationEndpoints/{endpointID}v2 API - 图648

/api/v2/notificationEndpoints/{endpointID}

Request samples

  • Payload

Content type

application/json

Example

http

v2 API - 图649

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

http

v2 API - 图650

http

pagerduty

slack

telegram

NotificationEndpoint

PostNotificationEndpoint

Copy

Expand all Collapse all

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

List all labels for a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

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

OpenTracing span context

Responses

v2 API - 图651200

A list of all labels for a notification endpoint

v2 API - 图652default

Unexpected error

get/api/v2/notificationEndpoints/{endpointID}/labelsv2 API - 图653

/api/v2/notificationEndpoints/{endpointID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

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

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图654201

The label was added to the notification endpoint

v2 API - 图655default

Unexpected error

post/api/v2/notificationEndpoints/{endpointID}/labelsv2 API - 图656

/api/v2/notificationEndpoints/{endpointID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label from a notification endpoint

Authorizations:

TokenAuthentication

path Parameters
endpointID
required
string

The notification endpoint ID.

labelID
required
string

The ID of the label to delete.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图657404

Endpoint or label not found

v2 API - 图658default

Unexpected error

delete/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}v2 API - 图659

/api/v2/notificationEndpoints/{endpointID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图660200

A list of notification rules

v2 API - 图661default

Unexpected error

get/api/v2/notificationRulesv2 API - 图662

/api/v2/notificationRules

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a notification rule

Authorizations:

TokenAuthentication

Request Body schema: application/json

Notification rule to create

description
string

An optional description of the notification rule.

endpointID
required
string
every
string

The notification repetition interval.

Array of objects (Labels)
limit
integer

Don’t notify me more than times every seconds. If set, limitEvery cannot be empty.

limitEvery
integer

Don’t notify me more than times every seconds. If set, limit cannot be empty.

name
required
string

Human-readable name describing the notification rule.

offset
string

Duration to delay after the schedule, before executing check.

orgID
required
string

The ID of the organization that owns this notification rule.

runbookLink
string
sleepUntil
string
status
required
string (TaskStatusType)
Enum: “active” “inactive”

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

required
Array of objects (StatusRule) non-empty

List of status rules the notification rule attempts to match.

Array of objects (TagRule)

List of tag rules the notification rule attempts to match.

taskID
string

The ID of the task associated with this notification rule.

type
required
string
http
v2 API - 图666
PostNotificationRule
NotificationRule
telegram
smtp
slack
pagerduty
http
url
string

Responses

v2 API - 图667201

Notification rule created

v2 API - 图668default

Unexpected error

post/api/v2/notificationRulesv2 API - 图669

/api/v2/notificationRules

Request samples

  • Payload

Content type

application/json

Example

http

v2 API - 图670

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Example

http

v2 API - 图671

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

Delete a notification rule

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图672404

The check was not found

v2 API - 图673default

Unexpected error

delete/api/v2/notificationRules/{ruleID}v2 API - 图674

/api/v2/notificationRules/{ruleID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图675200

The notification rule requested

v2 API - 图676default

Unexpected error

get/api/v2/notificationRules/{ruleID}v2 API - 图677

/api/v2/notificationRules/{ruleID}

Response samples

  • 200
  • default

Content type

application/json

Example

http

v2 API - 图678

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

Update a notification rule

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Request Body schema: application/json

Notification rule update to apply

description
string
name
string
status
string
Enum: “active” “inactive”

Responses

v2 API - 图679200

An updated notification rule

v2 API - 图680404

The notification rule was not found

v2 API - 图681default

Unexpected error

patch/api/v2/notificationRules/{ruleID}v2 API - 图682

/api/v2/notificationRules/{ruleID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

http

v2 API - 图683

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

Update a notification rule

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Request Body schema: application/json

Notification rule update to apply

description
string

An optional description of the notification rule.

endpointID
required
string
every
string

The notification repetition interval.

Array of objects (Labels)
limit
integer

Don’t notify me more than times every seconds. If set, limitEvery cannot be empty.

limitEvery
integer

Don’t notify me more than times every seconds. If set, limit cannot be empty.

name
required
string

Human-readable name describing the notification rule.

offset
string

Duration to delay after the schedule, before executing check.

orgID
required
string

The ID of the organization that owns this notification rule.

runbookLink
string
sleepUntil
string
status
required
string (TaskStatusType)
Enum: “active” “inactive”

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

required
Array of objects (StatusRule) non-empty

List of status rules the notification rule attempts to match.

Array of objects (TagRule)

List of tag rules the notification rule attempts to match.

taskID
string

The ID of the task associated with this notification rule.

type
required
string
http
v2 API - 图687
PostNotificationRule
NotificationRule
telegram
smtp
slack
pagerduty
http
url
string

Responses

v2 API - 图688200

An updated notification rule

v2 API - 图689404

The notification rule was not found

v2 API - 图690default

Unexpected error

put/api/v2/notificationRules/{ruleID}v2 API - 图691

/api/v2/notificationRules/{ruleID}

Request samples

  • Payload

Content type

application/json

Example

http

v2 API - 图692

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 404
  • default

Content type

application/json

Example

http

v2 API - 图693

http

pagerduty

slack

smtp

telegram

NotificationRule

PostNotificationRule

Copy

Expand all Collapse all

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

List all labels for a notification rule

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Responses

v2 API - 图694200

A list of all labels for a notification rule

v2 API - 图695default

Unexpected error

get/api/v2/notificationRules/{ruleID}/labelsv2 API - 图696

/api/v2/notificationRules/{ruleID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a notification rule

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图697201

The label was added to the notification rule

v2 API - 图698default

Unexpected error

post/api/v2/notificationRules/{ruleID}/labelsv2 API - 图699

/api/v2/notificationRules/{ruleID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete label from a notification rule

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The ID of the label to delete.

ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图700404

Rule or label not found

v2 API - 图701default

Unexpected error

delete/api/v2/notificationRules/{ruleID}/labels/{labelID}v2 API - 图702

/api/v2/notificationRules/{ruleID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Organizations

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

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

List organizations

Lists organizations.

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

InfluxDB Cloud

  • Only returns the organization that owns the token passed in the request.
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

v2 API - 图703200

Success. The response body contains a list of organizations.

v2 API - 图704400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图705401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图706404

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

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

v2 API - 图707500

Internal server error. The server encountered an unexpected situation.

v2 API - 图708default

Non 2XX error response from server.

get/api/v2/orgsv2 API - 图709

/api/v2/orgs

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Create an organization

Creates an organization and returns the newly created organization.

InfluxDB Cloud

  • Doesn’t allow you to use this endpoint to create organizations.
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

v2 API - 图710201

Created. The response body contains the organization information.

v2 API - 图711400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图712401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图713404

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

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

v2 API - 图714500

Internal server error. The server encountered an unexpected situation.

v2 API - 图715default

Unexpected error

post/api/v2/orgsv2 API - 图716

/api/v2/orgs

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete an organization

Deletes an organization.

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

InfluxDB Cloud

  • Does the following when you send a delete request:

    1. Validates the request and queues the delete.
    2. Returns an HTTP 204 status code if queued; error otherwise.
    3. Handles the delete asynchronously.

InfluxDB OSS

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

Limitations

  • Only one organization can be deleted per request.
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

204

Success.

InfluxDB Cloud

  • The organization is queued for deletion.

InfluxDB OSS

  • The organization is deleted.

v2 API - 图717400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图718401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图719404

Not found. InfluxDB can’t find the organization.

v2 API - 图720500

Internal server error. The server encountered an unexpected situation.

v2 API - 图721default

Unexpected error

delete/api/v2/orgs/{orgID}v2 API - 图722

/api/v2/orgs/{orgID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图723200

Success. The response body contains the organization information.

v2 API - 图724401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图725404

Not found. Organization not found.

v2 API - 图726500

Internal server error. The server encountered an unexpected situation.

v2 API - 图727default

Unexpected error

get/api/v2/orgs/{orgID}v2 API - 图728

/api/v2/orgs/{orgID}

Response samples

  • 200
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update an organization

Updates an organization.

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

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

  • Queries
  • Dashboards
  • Tasks
  • Telegraf configurations
  • Templates

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

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

v2 API - 图729200

Success. The response body contains the updated organization.

v2 API - 图730400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图731401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图732404

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

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

v2 API - 图733500

Internal server error. The server encountered an unexpected situation.

v2 API - 图734default

Unexpected error

patch/api/v2/orgs/{orgID}v2 API - 图735

/api/v2/orgs/{orgID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all members of an organization

Lists all users that belong to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

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

v2 API - 图736200

Success. The response body contains a list of all users within the organization.

v2 API - 图737400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图738401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图739404

Not found. InfluxDB can’t find the organization.

v2 API - 图740500

Internal server error. The server encountered an unexpected situation.

v2 API - 图741default

Unexpected error

get/api/v2/orgs/{orgID}/membersv2 API - 图742

/api/v2/orgs/{orgID}/members

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a member to an organization

Add a user to an organization.

InfluxDB users have permission to access InfluxDB.

Members are users within the organization.

InfluxDB Cloud

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

v2 API - 图743201

Success. The response body contains the user information.

v2 API - 图744400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图745401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图746404

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

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

v2 API - 图747500

Internal server error. The server encountered an unexpected situation.

v2 API - 图748default

Unexpected error

post/api/v2/orgs/{orgID}/membersv2 API - 图749

/api/v2/orgs/{orgID}/members

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from an organization

Removes a member from an organization.

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

InfluxDB Cloud

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

204

Success. The user is no longer a member of the organization.

v2 API - 图750401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图751404

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

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

v2 API - 图752500

Internal server error. The server encountered an unexpected situation.

v2 API - 图753default

Unexpected error

delete/api/v2/orgs/{orgID}/members/{userID}v2 API - 图754

/api/v2/orgs/{orgID}/members/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图755200

A list of organization owners

v2 API - 图756404

Organization not found

v2 API - 图757default

Unexpected error

get/api/v2/orgs/{orgID}/ownersv2 API - 图758

/api/v2/orgs/{orgID}/owners

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add an owner to an organization

Adds an owner to an organization.

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

InfluxDB Cloud

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

v2 API - 图759201

Success. The user is an owner of the organization. The response body contains the owner with role and user detail.

v2 API - 图760400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图761401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图762404

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

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

v2 API - 图763500

Internal server error. The server encountered an unexpected situation.

v2 API - 图764default

Unexpected error

post/api/v2/orgs/{orgID}/ownersv2 API - 图765

/api/v2/orgs/{orgID}/owners

Request samples

  • Payload
  • cURL

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove an owner from an organization

Removes an owner from the organization.

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

InfluxDB Cloud

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

204

Success. The user is no longer an owner of the organization.

v2 API - 图766401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图767404

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

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

v2 API - 图768500

Internal server error. The server encountered an unexpected situation.

v2 API - 图769default

Unexpected error

delete/api/v2/orgs/{orgID}/owners/{userID}v2 API - 图770

/api/v2/orgs/{orgID}/owners/{userID}

Response samples

  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Ping

Get the status of the instance

Retrieves the status and InfluxDB version of the instance.

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

InfluxDB Cloud

  • Isn’t versioned and doesn’t return X-Influxdb-Version in the headers.
Authorizations:

TokenAuthentication

Responses

v2 API - 图771204

Success. Headers contain InfluxDB version information.

get/pingv2 API - 图772

/ping

Request samples

  • cURL

Copy

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

Get the status of the instance

Returns the status and InfluxDB version of the instance.

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

InfluxDB Cloud

  • Isn’t versioned and doesn’t return X-Influxdb-Version in the headers.
Authorizations:

TokenAuthentication

Responses

v2 API - 图773204

Success. Headers contain InfluxDB version information.

head/pingv2 API - 图774

/ping

Request samples

  • cURL

Copy

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

Query

Retrieve data, analyze queries, and get query suggestions.

Query data

Retrieves data from buckets.

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

Rate limits (with InfluxDB Cloud)

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

Authorizations:

TokenAuthentication

query Parameters
org
string

An organization name or ID.

InfluxDB Cloud

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

InfluxDB OSS

  • Requires either the org parameter or orgID parameter.
  • Queries the bucket in the specified organization.
orgID
string

An organization ID.

InfluxDB Cloud

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

InfluxDB OSS

  • Requires either the org parameter or orgID parameter.
  • Queries the bucket in the specified organization.
header Parameters
Accept-Encoding
string
Default: identity
Enum: “gzip” “identity”

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

Content-Type
string
Enum: “application/json” “application/vnd.flux”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema:

application/json

v2 API - 图775

application/json

application/vnd.flux

Flux query or specification to execute

object (Dialect)

Options for tabular data output. Default output is annotated CSV with headers.

For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.

object (File)

Represents a source from a single file

now
string <date-time>

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

query
required
string

The query script to execute.

type
string
Value: “flux”

The type of query. Must be “flux”.

Responses

v2 API - 图778200

Success. The response body contains query results.

v2 API - 图779400

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

InfluxDB OSS

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

v2 API - 图780401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图781404

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

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

v2 API - 图782429

InfluxDB Cloud:

  • returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit
  • returns Retry-After header that describes when to try the write again.

InfluxDB OSS:

  • doesn’t return this error.

v2 API - 图783500

Internal server error. The server encountered an unexpected situation.

v2 API - 图784default

Non 2XX error response from server.

post/api/v2/queryv2 API - 图785

/api/v2/query

Request samples

  • Payload
  • cURL

Content type

application/json

v2 API - 图786

application/json

application/vnd.flux

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/csv

Copy

  1. result,table,_start,_stop,_time,region,host,_value
  2. mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:00Z,east,A,15.43
  3. mean,0,2018-05-08T20:50:00Z,2018-05-08T20:51:00Z,2018-05-08T20:50:20Z,east,B,59.25
  4. 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.

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

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:

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

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

Authorizations:

TokenAuthentication

header Parameters
Content-Type
string
Value: “application/json”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Flux query to analyze

object (Dialect)

Options for tabular data output. Default output is annotated CSV with headers.

For more information about tabular data dialect, see W3 metadata vocabulary for tabular data.

object (File)

Represents a source from a single file

now
string <date-time>

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

query
required
string

The query script to execute.

type
string
Value: “flux”

The type of query. Must be “flux”.

Responses

v2 API - 图789200

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

v2 API - 图790400

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

v2 API - 图791default

Internal server error

post/api/v2/query/analyzev2 API - 图792

/api/v2/query/analyze

Request samples

  • Payload
  • cURL: Analyze a Flux query

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 200
  • 400
  • default

Content type

application/json

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

The following sample query is missing the bucket property key:

  1. {
  2.   "query": "from(: \"iot_center\")\
  3.   ...
  4. }

Copy

Expand all Collapse all

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

Generate a query Abstract Syntax Tree (AST)

Analyzes a Flux query and returns a complete package source Abstract Syntax Tree (AST) for the query.

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

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

Limitations

  • The endpoint doesn’t validate values in the query—for example:

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

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

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

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

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

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

    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

v2 API - 图793200

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

v2 API - 图794400

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

v2 API - 图795default

Internal server error.

post/api/v2/query/astv2 API - 图796

/api/v2/query/ast

Request samples

  • Payload
  • cURL: Analyze and generate AST for the query

Content type

application/json

Copy

Expand all Collapse all

{ - "query": "string" }

Response samples

  • 200
  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "ast": { - "files": [ - { - "body": [ - { - "expression": { - "argument": { - "argument": { - "arguments": [ - { - "location": { - "end": { - "column": 25, - "line": 1 }, - "source": "bucket: \"example-bucket\"", - "start": { - "column": 6, - "line": 1 } }, - "properties": [ - { - "key": { - "location": { - "end": { - "column": 12, - "line": 1 }, - "source": "bucket", - "start": { - "column": 6, - "line": 1 } }, - "name": "bucket", - "type": "Identifier" }, - "location": { - "end": { - "column": 25, - "line": 1 }, - "source": "bucket: \"example-bucket\"", - "start": { - "column": 6, - "line": 1 } }, - "type": "Property", - "value": { - "location": { - "end": { - "column": 25, - "line": 1 }, - "source": "\"example-bucket\"", - "start": { - "column": 14, - "line": 1 } }, - "type": "StringLiteral", - "value": "example-bucket" } } ], - "type": "ObjectExpression" } ], - "callee": { - "location": { - "end": { - "column": 5, - "line": 1 }, - "source": "from", - "start": { - "column": 1, - "line": 1 } }, - "name": "from", - "type": "Identifier" }, - "location": { - "end": { - "column": 26, - "line": 1 }, - "source": "from(bucket: \"example-bucket\")", - "start": { - "column": 1, - "line": 1 } }, - "type": "CallExpression" }, - "call": { - "arguments": [ - { - "location": { - "end": { - "column": 46, - "line": 1 }, - "source": "start: -5m", - "start": { - "column": 36, - "line": 1 } }, - "properties": [ - { - "key": { - "location": { - "end": { - "column": 41, - "line": 1 }, - "source": "start", - "start": { - "column": 36, - "line": 1 } }, - "name": "start", - "type": "Identifier" }, - "location": { - "end": { - "column": 46, - "line": 1 }, - "source": "start: -5m", - "start": { - "column": 36, - "line": 1 } }, - "type": "Property", - "value": { - "argument": { - "location": { - "end": { - "column": 46, - "line": 1 }, - "source": "5m", - "start": { - "column": 44, - "line": 1 } }, - "type": "DurationLiteral", - "values": [ - { - "magnitude": 5, - "unit": "m" } ] }, - "location": { - "end": { - "column": 46, - "line": 1 }, - "source": "-5m", - "start": { - "column": 43, - "line": 1 } }, - "operator": "-", - "type": "UnaryExpression" } } ], - "type": "ObjectExpression" } ], - "callee": { - "location": { - "end": { - "column": 35, - "line": 1 }, - "source": "range", - "start": { - "column": 30, - "line": 1 } }, - "name": "range", - "type": "Identifier" }, - "location": { - "end": { - "column": 47, - "line": 1 }, - "source": "range(start: -5m)", - "start": { - "column": 30, - "line": 1 } }, - "type": "CallExpression" }, - "location": { - "end": { - "column": 47, - "line": 1 }, - "source": "from(bucket: \"example-bucket\") |> range(start: -5m)", - "start": { - "column": 1, - "line": 1 } }, - "type": "PipeExpression" }, - "call": { - "arguments": [ - { - "location": { - "end": { - "column": 108, - "line": 1 }, - "source": "fn: (r) => r._measurement == \"example-measurement\"", - "start": { - "column": 58, - "line": 1 } }, - "properties": [ - { - "key": { - "location": { - "end": { - "column": 60, - "line": 1 }, - "source": "fn", - "start": { - "column": 58, - "line": 1 } }, - "name": "fn", - "type": "Identifier" }, - "location": { - "end": { - "column": 108, - "line": 1 }, - "source": "fn: (r) => r._measurement == \"example-measurement\"", - "start": { - "column": 58, - "line": 1 } }, - "type": "Property", - "value": { - "body": { - "left": { - "location": { - "end": { - "column": 83, - "line": 1 }, - "source": "r._measurement", - "start": { - "column": 69, - "line": 1 } }, - "object": { - "location": { - "end": { - "column": 70, - "line": 1 }, - "source": "r", - "start": { - "column": 69, - "line": 1 } }, - "name": "r", - "type": "Identifier" }, - "property": { - "location": { - "end": { - "column": 83, - "line": 1 }, - "source": "_measurement", - "start": { - "column": 71, - "line": 1 } }, - "name": "_measurement", - "type": "Identifier" }, - "type": "MemberExpression" }, - "location": { - "end": { - "column": 108, - "line": 1 }, - "source": "r._measurement == \"example-measurement\"", - "start": { - "column": 69, - "line": 1 } }, - "operator": "==", - "right": { - "location": { - "end": { - "column": 108, - "line": 1 }, - "source": "\"example-measurement\"", - "start": { - "column": 87, - "line": 1 } }, - "type": "StringLiteral", - "value": "example-measurement" }, - "type": "BinaryExpression" }, - "location": { - "end": { - "column": 108, - "line": 1 }, - "source": "(r) => r._measurement == \"example-measurement\"", - "start": { - "column": 62, - "line": 1 } }, - "params": [ - { - "key": { - "location": { - "end": { - "column": 64, - "line": 1 }, - "source": "r", - "start": { - "column": 63, - "line": 1 } }, - "name": "r", - "type": "Identifier" }, - "location": { - "end": { - "column": 64, - "line": 1 }, - "source": "r", - "start": { - "column": 63, - "line": 1 } }, - "type": "Property", - "value": null } ], - "type": "FunctionExpression" } } ], - "type": "ObjectExpression" } ], - "callee": { - "location": { - "end": { - "column": 57, - "line": 1 }, - "source": "filter", - "start": { - "column": 51, - "line": 1 } }, - "name": "filter", - "type": "Identifier" }, - "location": { - "end": { - "column": 109, - "line": 1 }, - "source": "filter(fn: (r) => r._measurement == \"example-measurement\")", - "start": { - "column": 51, - "line": 1 } }, - "type": "CallExpression" }, - "location": { - "end": { - "column": 109, - "line": 1 }, - "source": "from(bucket: \"example-bucket\") |> range(start: -5m) |> filter(fn: (r) => r._measurement == \"example-measurement\")", - "start": { - "column": 1, - "line": 1 } }, - "type": "PipeExpression" }, - "location": { - "end": { - "column": 109, - "line": 1 }, - "source": "from(bucket: \"example-bucket\") |> range(start: -5m) |> filter(fn: (r) => r._measurement == \"example-measurement\")", - "start": { - "column": 1, - "line": 1 } }, - "type": "ExpressionStatement" } ], - "imports": null, - "location": { - "end": { - "column": 109, - "line": 1 }, - "source": "from(bucket: \"example-bucket\") |> range(start: -5m) |> filter(fn: (r) => r._measurement == \"example-measurement\")", - "start": { - "column": 1, - "line": 1 } }, - "metadata": "parser-type=rust", - "package": null, - "type": "File" } ], - "package": "main", - "type": "Package" } }

List Flux query suggestions

Lists Flux query suggestions. Each suggestion contains a Flux function name and parameters.

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

Limitations

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

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

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图797200

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

v2 API - 图798301

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

v2 API - 图799default

Internal server error.

get/api/v2/query/suggestionsv2 API - 图800

/api/v2/query/suggestions

Request samples

  • cURL

Copy

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

Response samples

  • 200
  • 301
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a query suggestion for a branching suggestion

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

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

Limitations

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

  • The function name must exist and must be spelled correctly.

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

v2 API - 图801200

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

v2 API - 图802500

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

get/api/v2/query/suggestions/{name}v2 API - 图803

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

Request samples

  • cURL

Copy

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

Response samples

  • 200
  • 500

Content type

application/json

Copy

Expand all Collapse all

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

Ready

Get the readiness of an instance at startup

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图804200

The instance is ready

v2 API - 图805default

Non 2XX error response from server.

get/readyv2 API - 图806

/ready

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

RemoteConnections

List all remote connections

Authorizations:

TokenAuthentication

query Parameters
name
string
orgID
required
string

The organization ID.

remoteURL
string <uri>
header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图807200

List of remote connections

v2 API - 图808404

Non 2XX error response from server.

v2 API - 图809default

Non 2XX error response from server.

get/api/v2/remotesv2 API - 图810

/api/v2/remotes

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Register a new remote connection

Authorizations:

TokenAuthentication

Request Body schema: application/json
allowInsecureTLS
required
boolean
Default: false
description
string
name
required
string
orgID
required
string
remoteAPIToken
required
string
remoteOrgID
string
remoteURL
required
string <uri>

Responses

v2 API - 图811201

Remote connection saved

v2 API - 图812400

Non 2XX error response from server.

v2 API - 图813default

Non 2XX error response from server.

post/api/v2/remotesv2 API - 图814

/api/v2/remotes

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecureTLS": false, - "description": "string", - "name": "string", - "orgID": "string", - "remoteAPIToken": "string", - "remoteOrgID": "string", - "remoteURL": "[http://example.com](http://example.com)" }

Response samples

  • 201
  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a remote connection

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

204

Remote connection info deleted.

v2 API - 图815404

Non 2XX error response from server.

v2 API - 图816default

Non 2XX error response from server.

delete/api/v2/remotes/{remoteID}v2 API - 图817

/api/v2/remotes/{remoteID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a remote connection

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图818200

Remote connection

v2 API - 图819404

Non 2XX error response from server.

v2 API - 图820default

Non 2XX error response from server.

get/api/v2/remotes/{remoteID}v2 API - 图821

/api/v2/remotes/{remoteID}

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a remote connection

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json
allowInsecureTLS
boolean
Default: false
description
string
name
string
remoteAPIToken
string
remoteOrgID
string
remoteURL
string <uri>

Responses

v2 API - 图822200

Updated information saved

v2 API - 图823400

Non 2XX error response from server.

v2 API - 图824404

Non 2XX error response from server.

v2 API - 图825default

Non 2XX error response from server.

patch/api/v2/remotes/{remoteID}v2 API - 图826

/api/v2/remotes/{remoteID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecureTLS": false, - "description": "string", - "name": "string", - "remoteAPIToken": "string", - "remoteOrgID": "string", - "remoteURL": "[http://example.com](http://example.com)" }

Response samples

  • 200
  • 400
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Replications

List all replications

Authorizations:

TokenAuthentication

query Parameters
localBucketID
string
name
string
orgID
required
string

The organization ID.

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

OpenTracing span context

Responses

v2 API - 图827200

List of replications

v2 API - 图828404

Non 2XX error response from server.

v2 API - 图829default

Non 2XX error response from server.

get/api/v2/replicationsv2 API - 图830

/api/v2/replications

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "replications": [ - { - "currentQueueSizeBytes": 0, - "description": "string", - "dropNonRetryableData": true, - "id": "string", - "latestErrorMessage": "string", - "latestResponseCode": 0, - "localBucketID": "string", - "maxQueueSizeBytes": 0, - "name": "string", - "orgID": "string", - "remainingBytesToBeSynced": 0, - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" } ] }

Register a new replication

Authorizations:

TokenAuthentication

query Parameters
validate
boolean
Default: false

If true, validate the replication, but don’t save it.

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

OpenTracing span context

Request Body schema: application/json
description
string
dropNonRetryableData
boolean
Default: false
localBucketID
required
string
maxAgeSeconds
required
integer <int64> >= 0
Default: 604800
maxQueueSizeBytes
required
integer <int64> >= 33554430
Default: 67108860
name
required
string
orgID
required
string
remoteBucketID
string
remoteBucketName
string
remoteID
required
string

Responses

v2 API - 图831201

Replication saved

204

Replication validated, but not saved

v2 API - 图832400

Non 2XX error response from server.

v2 API - 图833default

Non 2XX error response from server.

post/api/v2/replicationsv2 API - 图834

/api/v2/replications

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "description": "string", - "dropNonRetryableData": false, - "localBucketID": "string", - "maxAgeSeconds": 604800, - "maxQueueSizeBytes": 67108860, - "name": "string", - "orgID": "string", - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" }

Response samples

  • 201
  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "currentQueueSizeBytes": 0, - "description": "string", - "dropNonRetryableData": true, - "id": "string", - "latestErrorMessage": "string", - "latestResponseCode": 0, - "localBucketID": "string", - "maxQueueSizeBytes": 0, - "name": "string", - "orgID": "string", - "remainingBytesToBeSynced": 0, - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" }

Delete a replication

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

204

Replication deleted.

v2 API - 图835404

Non 2XX error response from server.

v2 API - 图836default

Non 2XX error response from server.

delete/api/v2/replications/{replicationID}v2 API - 图837

/api/v2/replications/{replicationID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a replication

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图838200

Replication

v2 API - 图839404

Non 2XX error response from server.

v2 API - 图840default

Non 2XX error response from server.

get/api/v2/replications/{replicationID}v2 API - 图841

/api/v2/replications/{replicationID}

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "currentQueueSizeBytes": 0, - "description": "string", - "dropNonRetryableData": true, - "id": "string", - "latestErrorMessage": "string", - "latestResponseCode": 0, - "localBucketID": "string", - "maxQueueSizeBytes": 0, - "name": "string", - "orgID": "string", - "remainingBytesToBeSynced": 0, - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" }

Update a replication

Authorizations:

TokenAuthentication

path Parameters
replicationID
required
string
query Parameters
validate
boolean
Default: false

If true, validate the updated information, but don’t save it.

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

OpenTracing span context

Request Body schema: application/json
description
string
dropNonRetryableData
boolean
maxAgeSeconds
integer <int64> >= 0
maxQueueSizeBytes
integer <int64> >= 33554430
name
string
remoteBucketID
string
remoteBucketName
string
remoteID
string

Responses

v2 API - 图842200

Updated information saved

204

Updated replication validated, but not saved

v2 API - 图843400

Non 2XX error response from server.

v2 API - 图844404

Non 2XX error response from server.

v2 API - 图845default

Non 2XX error response from server.

patch/api/v2/replications/{replicationID}v2 API - 图846

/api/v2/replications/{replicationID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "description": "string", - "dropNonRetryableData": true, - "maxAgeSeconds": 0, - "maxQueueSizeBytes": 33554430, - "name": "string", - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" }

Response samples

  • 200
  • 400
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "currentQueueSizeBytes": 0, - "description": "string", - "dropNonRetryableData": true, - "id": "string", - "latestErrorMessage": "string", - "latestResponseCode": 0, - "localBucketID": "string", - "maxQueueSizeBytes": 0, - "name": "string", - "orgID": "string", - "remainingBytesToBeSynced": 0, - "remoteBucketID": "string", - "remoteBucketName": "string", - "remoteID": "string" }

Validate a replication

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

204

Replication is valid

v2 API - 图847400

Non 2XX error response from server.

v2 API - 图848default

Non 2XX error response from server.

post/api/v2/replications/{replicationID}/validatev2 API - 图849

/api/v2/replications/{replicationID}/validate

Response samples

  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Resources

List all known resources

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图850200

All resources targets

v2 API - 图851default

Internal server error

get/api/v2/resourcesv2 API - 图852

/api/v2/resources

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

[ - "string" ]

Restore

Overwrite storage metadata for a bucket with shard info from a backup. Deprecated

Authorizations:

TokenAuthentication

path Parameters
bucketID
required
string

The bucket ID.

header Parameters
Content-Type
string
Default: application/octet-stream
Value: “application/octet-stream”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: text/plain

Database info serialized as protobuf.

string <byte>

Responses

v2 API - 图853200

ID mappings for shards in bucket.

v2 API - 图854default

Non 2XX error response from server.

post/api/v2/restore/bucket/{bucketID}v2 API - 图855

/api/v2/restore/bucket/{bucketID}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

"string"

Create a new bucket pre-seeded with shard info from a backup.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

Metadata manifest for a bucket.

bucketID
required
string
bucketName
required
string
defaultRetentionPolicy
required
string
description
string
organizationID
required
string
organizationName
required
string
required
Array of objects (RetentionPolicyManifests)

Responses

v2 API - 图857201

ID mappings for shards in new bucket.

v2 API - 图858default

Non 2XX error response from server.

post/api/v2/restore/bucketMetadatav2 API - 图859

/api/v2/restore/bucketMetadata

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "bucketID": "string", - "bucketName": "string", - "defaultRetentionPolicy": "string", - "description": "string", - "organizationID": "string", - "organizationName": "string", - "retentionPolicies": [ - { - "duration": 0, - "name": "string", - "replicaN": 0, - "shardGroupDuration": 0, - "shardGroups": [ - { - "deletedAt": "2019-08-24T14:15:22Z", - "endTime": "2019-08-24T14:15:22Z", - "id": 0, - "shards": [ - { - "id": 0, - "shardOwners": [ - { - "nodeID": 0 } ] } ], - "startTime": "2019-08-24T14:15:22Z", - "truncatedAt": "2019-08-24T14:15:22Z" } ], - "subscriptions": [ - { - "destinations": [ - "string" ], - "mode": "string", - "name": "string" } ] } ] }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "name": "string", - "shardMappings": [ - { - "newId": 0, - "oldId": 0 } ] }

Overwrite the embedded KV store on the server with a backed-up snapshot.

Authorizations:

TokenAuthentication

header Parameters
Content-Encoding
string
Default: identity
Enum: “gzip” “identity”

The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip payload, send Content-Encoding: gzip as a request header.

Content-Type
string
Default: application/octet-stream
Value: “application/octet-stream”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: text/plain

Full KV snapshot.

string <binary>

Responses

v2 API - 图860200

KV store successfully overwritten.

204

KV store successfully overwritten.

v2 API - 图861default

Non 2XX error response from server.

post/api/v2/restore/kvv2 API - 图862

/api/v2/restore/kv

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "token": "string" }

Restore a TSM snapshot into a shard.

Authorizations:

TokenAuthentication

path Parameters
shardID
required
string

The shard ID.

header Parameters
Content-Encoding
string
Default: identity
Enum: “gzip” “identity”

The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip payload, send Content-Encoding: gzip as a request header.

Content-Type
string
Default: application/octet-stream
Value: “application/octet-stream”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: text/plain

TSM snapshot.

string <binary>

Responses

204

TSM snapshot successfully restored.

v2 API - 图863default

Non 2XX error response from server.

post/api/v2/restore/shards/{shardID}v2 API - 图864

/api/v2/restore/shards/{shardID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Overwrite the embedded SQL store on the server with a backed-up snapshot.

Authorizations:

TokenAuthentication

header Parameters
Content-Encoding
string
Default: identity
Enum: “gzip” “identity”

The value tells InfluxDB what compression is applied to the line protocol in the request payload. To make an API request with a gzip-compressed payload, send Content-Encoding: gzip as a request header.

Content-Type
string
Default: application/octet-stream
Value: “application/octet-stream”
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: text/plain

Full SQL snapshot.

string <binary>

Responses

204

SQL store successfully overwritten.

v2 API - 图865default

Non 2XX error response from server.

post/api/v2/restore/sqlv2 API - 图866

/api/v2/restore/sql

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Routes

List all top level routes

Retrieves all the top level routes for the InfluxDB API.

Limitations

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

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图867200

Success. The response body contains key-value pairs with the resource name and top-level route.

get/api/v2v2 API - 图868

/api/v2

Response samples

  • 200

Content type

application/json

Copy

Expand all Collapse all

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

Rules

Retrieve a notification rule query

Authorizations:

TokenAuthentication

path Parameters
ruleID
required
string

The notification rule ID.

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

OpenTracing span context

Responses

v2 API - 图869200

The notification rule query requested

v2 API - 图870400

Invalid request

v2 API - 图871404

Notification rule not found

v2 API - 图872default

Unexpected error

get/api/v2/notificationRules/{ruleID}/queryv2 API - 图873

/api/v2/notificationRules/{ruleID}/query

Response samples

  • 200
  • 400
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "flux": "string" }

Scraper Targets

List all scraper targets

Authorizations:

TokenAuthentication

query Parameters
id
Array of strings

List of scraper target IDs to return. If both id and owner are specified, only id is used.

name
string

Specifies the name of the scraper target.

org
string

Specifies the organization name of the scraper target.

orgID
string

Specifies the organization ID of the scraper target.

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

OpenTracing span context

Responses

v2 API - 图874200

All scraper targets

get/api/v2/scrapersv2 API - 图875

/api/v2/scrapers

Response samples

  • 200

Content type

application/json

Copy

Expand all Collapse all

{ - "configurations": [ - { - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)", - "bucket": "string", - "id": "string", - "links": { - "bucket": "/api/v2/buckets/1", - "members": "/api/v2/scrapers/1/members", - "organization": "/api/v2/orgs/1", - "owners": "/api/v2/scrapers/1/owners", - "self": "/api/v2/scrapers/1" }, - "org": "string" } ] }

Create a scraper target

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

Scraper target to create

allowInsecure
boolean
Default: false

Skip TLS verification on endpoint.

bucketID
string

The ID of the bucket to write to.

name
string

The name of the scraper target.

orgID
string

The organization ID.

type
string
Value: “prometheus”

The type of the metrics to be parsed.

url
string

The URL of the metrics endpoint.

Responses

v2 API - 图876201

Scraper target created

v2 API - 图877default

Internal server error

post/api/v2/scrapersv2 API - 图878

/api/v2/scrapers

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)", - "bucket": "string", - "id": "string", - "links": { - "bucket": "/api/v2/buckets/1", - "members": "/api/v2/scrapers/1/members", - "organization": "/api/v2/orgs/1", - "owners": "/api/v2/scrapers/1/owners", - "self": "/api/v2/scrapers/1" }, - "org": "string" }

Delete a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The identifier of the scraper target.

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

OpenTracing span context

Responses

204

Scraper target deleted

v2 API - 图879default

Internal server error

delete/api/v2/scrapers/{scraperTargetID}v2 API - 图880

/api/v2/scrapers/{scraperTargetID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The identifier of the scraper target.

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

OpenTracing span context

Responses

v2 API - 图881200

The scraper target

v2 API - 图882default

Internal server error

get/api/v2/scrapers/{scraperTargetID}v2 API - 图883

/api/v2/scrapers/{scraperTargetID}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)", - "bucket": "string", - "id": "string", - "links": { - "bucket": "/api/v2/buckets/1", - "members": "/api/v2/scrapers/1/members", - "organization": "/api/v2/orgs/1", - "owners": "/api/v2/scrapers/1/owners", - "self": "/api/v2/scrapers/1" }, - "org": "string" }

Update a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The identifier of the scraper target.

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

OpenTracing span context

Request Body schema: application/json

Scraper target update to apply

allowInsecure
boolean
Default: false

Skip TLS verification on endpoint.

bucketID
string

The ID of the bucket to write to.

name
string

The name of the scraper target.

orgID
string

The organization ID.

type
string
Value: “prometheus”

The type of the metrics to be parsed.

url
string

The URL of the metrics endpoint.

Responses

v2 API - 图884200

Scraper target updated

v2 API - 图885default

Internal server error

patch/api/v2/scrapers/{scraperTargetID}v2 API - 图886

/api/v2/scrapers/{scraperTargetID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)" }

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "allowInsecure": false, - "bucketID": "string", - "name": "string", - "orgID": "string", - "type": "prometheus", - "url": "[http://localhost:9090/metrics](http://localhost:9090/metrics)", - "bucket": "string", - "id": "string", - "links": { - "bucket": "/api/v2/buckets/1", - "members": "/api/v2/scrapers/1/members", - "organization": "/api/v2/orgs/1", - "owners": "/api/v2/scrapers/1/owners", - "self": "/api/v2/scrapers/1" }, - "org": "string" }

List all labels for a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Responses

v2 API - 图887200

A list of labels for a scraper target.

v2 API - 图888default

Unexpected error

get/api/v2/scrapers/{scraperTargetID}/labelsv2 API - 图889

/api/v2/scrapers/{scraperTargetID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图890201

The newly added label

v2 API - 图891default

Unexpected error

post/api/v2/scrapers/{scraperTargetID}/labelsv2 API - 图892

/api/v2/scrapers/{scraperTargetID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label from a scraper target

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The label ID.

scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图893404

Scraper target not found

v2 API - 图894default

Unexpected error

delete/api/v2/scrapers/{scraperTargetID}/labels/{labelID}v2 API - 图895

/api/v2/scrapers/{scraperTargetID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all users with member privileges for a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Responses

v2 API - 图896200

A list of scraper target members

v2 API - 图897default

Unexpected error

get/api/v2/scrapers/{scraperTargetID}/membersv2 API - 图898

/api/v2/scrapers/{scraperTargetID}/members

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a member to a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Request Body schema: application/json

User to add as member

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图899201

Member added to scraper targets

v2 API - 图900default

Unexpected error

post/api/v2/scrapers/{scraperTargetID}/membersv2 API - 图901

/api/v2/scrapers/{scraperTargetID}/members

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

userID
required
string

The ID of member to remove.

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

OpenTracing span context

Responses

204

Member removed

v2 API - 图902default

Unexpected error

delete/api/v2/scrapers/{scraperTargetID}/members/{userID}v2 API - 图903

/api/v2/scrapers/{scraperTargetID}/members/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

List all owners of a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Responses

v2 API - 图904200

A list of scraper target owners

v2 API - 图905default

Unexpected error

get/api/v2/scrapers/{scraperTargetID}/ownersv2 API - 图906

/api/v2/scrapers/{scraperTargetID}/owners

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add an owner to a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

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

OpenTracing span context

Request Body schema: application/json

User to add as owner

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图907201

Scraper target owner added

v2 API - 图908default

Unexpected error

post/api/v2/scrapers/{scraperTargetID}/ownersv2 API - 图909

/api/v2/scrapers/{scraperTargetID}/owners

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove an owner from a scraper target

Authorizations:

TokenAuthentication

path Parameters
scraperTargetID
required
string

The scraper target ID.

userID
required
string

The ID of owner to remove.

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

OpenTracing span context

Responses

204

Owner removed

v2 API - 图910default

Unexpected error

delete/api/v2/scrapers/{scraperTargetID}/owners/{userID}v2 API - 图911

/api/v2/scrapers/{scraperTargetID}/owners/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Secrets

List all secret keys for an organization

Authorizations:

TokenAuthentication

path Parameters
orgID
required
string

The organization ID.

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

OpenTracing span context

Responses

v2 API - 图912200

A list of all secret keys

v2 API - 图913default

Unexpected error

get/api/v2/orgs/{orgID}/secretsv2 API - 图914

/api/v2/orgs/{orgID}/secrets

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update secrets in an organization

Authorizations:

TokenAuthentication

path Parameters
orgID
required
string

The organization ID.

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

OpenTracing span context

Request Body schema: application/json

Secret key value pairs to update/add

property name*
string

Responses

204

Keys successfully patched

v2 API - 图915default

Unexpected error

patch/api/v2/orgs/{orgID}/secretsv2 API - 图916

/api/v2/orgs/{orgID}/secrets

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "apikey": "abc123xyz" }

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Keys successfully deleted

v2 API - 图917default

Non 2XX error response from server.

delete/api/v2/orgs/{orgID}/secrets/{secretID}v2 API - 图918

/api/v2/orgs/{orgID}/secrets/{secretID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Keys successfully patched

v2 API - 图919default

Unexpected error

post/api/v2/orgs/{orgID}/secrets/deletev2 API - 图920

/api/v2/orgs/{orgID}/secrets/delete

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "secrets": [ - "string" ] }

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

Setup

Check if database has default user, org, bucket

Returns true if no default user, organization, or bucket has been created.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Responses

v2 API - 图921200

allowed true or false

get/api/v2/setupv2 API - 图922

/api/v2/setup

Response samples

  • 200

Content type

application/json

Copy

Expand all Collapse all

{ - "allowed": true }

Set up initial user, org and bucket

Post an onboarding request to set up initial user, org and bucket.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

Source to create

bucket
required
string
org
required
string
password
string
retentionPeriodHrs
integer
Deprecated

Retention period in nanoseconds for the new bucket. This key’s name has been misleading since OSS 2.0 GA, please transition to use retentionPeriodSeconds

retentionPeriodSeconds
integer <int64>
token
string

Authentication token to set on the initial user. If not specified, the server will generate a token.

username
required
string

Responses

v2 API - 图923201

Created default user, bucket, org

v2 API - 图924default

Non 2XX error response from server.

post/api/v2/setupv2 API - 图925

/api/v2/setup

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "bucket": "string", - "org": "string", - "password": "string", - "retentionPeriodHrs": 0, - "retentionPeriodSeconds": 0, - "token": "string", - "username": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "auth": { - "description": "string", - "status": "active", - "createdAt": "2019-08-24T14:15:22Z", - "id": "string", - "links": { - "self": "/api/v2/authorizations/1", - "user": "/api/v2/users/12" }, - "org": "string", - "orgID": "string", - "permissions": [ - { - "action": "read", - "resource": { - "id": "string", - "name": "string", - "org": "string", - "orgID": "string", - "type": "authorizations" } } ], - "token": "string", - "updatedAt": "2019-08-24T14:15:22Z", - "user": "string", - "userID": "string" }, - "bucket": { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/buckets/1/labels", - "members": "/api/v2/buckets/1/members", - "org": "/api/v2/orgs/2", - "owners": "/api/v2/buckets/1/owners", - "self": "/api/v2/buckets/1", - "write": "/api/v2/write?org=2&bucket=1" }, - "name": "string", - "orgID": "string", - "retentionRules": [ - { - "everySeconds": 86400, - "shardGroupDurationSeconds": 0, - "type": "expire" } ], - "rp": "string", - "schemaType": "implicit", - "type": "user", - "updatedAt": "2019-08-24T14:15:22Z" }, - "org": { - "createdAt": "2019-08-24T14:15:22Z", - "defaultStorageType": "tsm", - "description": "string", - "id": "string", - "links": { - "buckets": "/api/v2/buckets?org=myorg", - "dashboards": "/api/v2/dashboards?org=myorg", - "labels": "/api/v2/orgs/1/labels", - "members": "/api/v2/orgs/1/members", - "owners": "/api/v2/orgs/1/owners", - "secrets": "/api/v2/orgs/1/secrets", - "self": "/api/v2/orgs/1", - "tasks": "/api/v2/tasks?org=myorg" }, - "name": "string", - "status": "active", - "updatedAt": "2019-08-24T14:15:22Z" }, - "user": { - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" } }

Signin

Create a user session.

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

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

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

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

User sessions with authorizations

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

BasicAuthentication

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

OpenTracing span context

Responses

204

Success. The user is authenticated. The Set-Cookie response header contains the session cookie.

v2 API - 图926401

Unauthorized. This error may be caused by one of the following problems:

  • The user doesn’t have access.
  • The user passed incorrect credentials in the request.
  • The credentials are formatted incorrectly in the request.

v2 API - 图927403

Forbidden. The user account is disabled.

v2 API - 图928default

Unsuccessful authentication.

post/api/v2/signinv2 API - 图929

/api/v2/signin

Request samples

  • cURL: signin with —user option encoding

Copy

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

Response samples

  • 401
  • 403
  • default

Content type

application/json

Copy

Expand all Collapse all

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

204

Success. The session is expired.

v2 API - 图930401

Unauthorized.

v2 API - 图931default

The session expiry is unsuccessful.

post/api/v2/signoutv2 API - 图932

/api/v2/signout

Request samples

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

Copy

  1. # The following example shows how to use cURL and the InfluxDB API
  2. # to do the following:
  3. # 1. Sign in a user with a username and password.
  4. # 2. Check that the user session exists for the user.
  5. # 3. Sign out the user to expire the session.
  6. # 4. Check that the session is no longer active.
  8. # 1. Send a request to `POST /api/v2/signin` to sign in the user.
  9. #    In your request, pass the following:
  10. #
  11. #      - `--user` option with basic authentication credentials.
  12. #      - `-c` option with a file path where cURL will write cookies.
  14.       curl --request POST \
  15.         -c ./cookie-file.tmp \
  16.         "$INFLUX_URL/api/v2/signin" \
  17.         --user "${INFLUX_USER_NAME}:${INFLUX_USER_PASSWORD}"
  19. # 2. To check that a user session exists for the user in step 1,
  20. #    send a request to `GET /api/v2/me`.
  21. #    In your request, pass the `-b` option with the session cookie file path from step 1.
  23.       curl --request GET \
  24.         -b ./cookie-file.tmp \
  25.         "$INFLUX_URL/api/v2/me"
  27. #    InfluxDB responds with the `user` resource.
  29. # 3. Send a request to `POST /api/v2/signout` to expire the user session.
  30. #    In your request, pass the `-b` option with the session cookie file path from step 1.
  32.       curl --request POST \
  33.         -b ./cookie-file.tmp \
  34.         "$INFLUX_URL/api/v2/signout"
  36. #     If the user session is successfully expired, InfluxDB responds with
  37.       an HTTP `204` status code.
  39. # 4. To check that the user session is expired, call `GET /api/v2/me` again,
  40. #    passing the `-b` option with the cookie file path.
  42.       curl --request GET \
  43.         -b ./cookie-file.tmp \
  44.         "$INFLUX_URL/api/v2/me"
  46. #    If the user session is expired, InfluxDB responds with an HTTP `401` status code.

Response samples

  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Sources

List all sources

Authorizations:

TokenAuthentication

query Parameters
org
string

The name of the organization.

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

OpenTracing span context

Responses

v2 API - 图933200

A list of sources

v2 API - 图934default

Unexpected error

get/api/v2/sourcesv2 API - 图935

/api/v2/sources

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "links": { - "self": "[http://example.com](http://example.com)" }, - "sources": [ - { - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "languages": [ - "flux" ], - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" } ] }

Create a source

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

Source to create

default
boolean
defaultRP
string
id
string
insecureSkipVerify
boolean
object
metaUrl
string <uri>
name
string
orgID
string
password
string
sharedSecret
string
telegraf
string
token
string
type
string
Enum: “v1” “v2” “self”
url
string <uri>
username
string

Responses

v2 API - 图937201

Created Source

v2 API - 图938default

Unexpected error

post/api/v2/sourcesv2 API - 图939

/api/v2/sources

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "languages": [ - "flux" ], - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" }

Delete a source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

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

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图940404

View not found

v2 API - 图941default

Unexpected error

delete/api/v2/sources/{sourceID}v2 API - 图942

/api/v2/sources/{sourceID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

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

OpenTracing span context

Responses

v2 API - 图943200

A source

v2 API - 图944404

Source not found

v2 API - 图945default

Unexpected error

get/api/v2/sources/{sourceID}v2 API - 图946

/api/v2/sources/{sourceID}

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "languages": [ - "flux" ], - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" }

Update a Source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

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

OpenTracing span context

Request Body schema: application/json

Source update

default
boolean
defaultRP
string
id
string
insecureSkipVerify
boolean
object
metaUrl
string <uri>
name
string
orgID
string
password
string
sharedSecret
string
telegraf
string
token
string
type
string
Enum: “v1” “v2” “self”
url
string <uri>
username
string

Responses

v2 API - 图948200

Created Source

v2 API - 图949404

Source not found

v2 API - 图950default

Unexpected error

patch/api/v2/sources/{sourceID}v2 API - 图951

/api/v2/sources/{sourceID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" }

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "default": true, - "defaultRP": "string", - "id": "string", - "insecureSkipVerify": true, - "languages": [ - "flux" ], - "links": { - "buckets": "string", - "health": "string", - "query": "string", - "self": "string" }, - "metaUrl": "[http://example.com](http://example.com)", - "name": "string", - "orgID": "string", - "password": "string", - "sharedSecret": "string", - "telegraf": "string", - "token": "string", - "type": "v1", - "url": "[http://example.com](http://example.com)", - "username": "string" }

Get buckets in a source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

query Parameters
org
string

The name of the organization.

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

OpenTracing span context

Responses

v2 API - 图952200

A source

v2 API - 图953404

Source not found

v2 API - 图954default

Unexpected error

get/api/v2/sources/{sourceID}/bucketsv2 API - 图955

/api/v2/sources/{sourceID}/buckets

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Get the health of a source

Authorizations:

TokenAuthentication

path Parameters
sourceID
required
string

The source ID.

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

OpenTracing span context

Responses

v2 API - 图956200

The source is healthy

v2 API - 图957503

The source is not healthy

v2 API - 图958default

Unexpected error

get/api/v2/sources/{sourceID}/healthv2 API - 图959

/api/v2/sources/{sourceID}/health

Response samples

  • 200
  • 503
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Tasks

Process and analyze your data with tasks in the InfluxDB task engine. Use the /api/v2/tasks endpoints to schedule and manage tasks, retry task runs, and retrieve run logs.

To configure a task, provide the script and the schedule to run the task. For examples, see how to create a task with the POST /api/v2/tasks endpoint.

Properties

A task object contains information about an InfluxDB task resource.

The following table defines the properties that appear in a task object:

authorizationID
string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt
string <date-time>
cron
string

A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.

description
string

A description of the task.

every
string <duration>

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

flux
required
string <flux>

The Flux script that the task executes.

id
required
string
Array of objects (Labels)
lastRunError
string
lastRunStatus
string
Enum: “failed” “success” “canceled”
latestCompleted
string <date-time>

A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.

object
name
required
string

The name of the task.

offset
string <duration>

A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.

org
string

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

orgID
required
string

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

ownerID
string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

status
string (TaskStatusType)
Enum: “active” “inactive”

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

updatedAt
string <date-time>

Copy

Expand all Collapse all

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

List tasks

Retrieves a list of tasks.

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

Authorizations:

TokenAuthentication

query Parameters
after
string

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

limit
integer [ 1 .. 500 ]
Default: 100

The maximum number of tasks to return. Default is 100. The minimum is 1 and the maximum is 500.

To reduce the payload size, combine type=basic and limit (see Request samples). For more information about the basic response, see the type parameter.

name
string

A task name. Only returns tasks with the specified name. Different tasks may have the same name.

org
string

An organization name. Only returns tasks owned by the specified organization.

orgID
string

An organization ID. Only returns tasks owned by the specified organization.

status
string
Enum: “active” “inactive”

A task status. Only returns tasks that have the specified status (active or inactive).

type
string
Default: “”
Enum: “basic” “system”

A task type (basic or system). Default is system. Specifies the level of detail for tasks in the response. The default (system) response contains all the metadata properties for tasks. To reduce the response size, pass basic to omit some task properties (flux, createdAt, updatedAt).

user
string

A user ID. Only returns tasks owned by the specified user.

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

OpenTracing span context

Responses

v2 API - 图962200

Success. The response body contains the list of tasks.

v2 API - 图963401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图964500

Internal server error. The server encountered an unexpected situation.

v2 API - 图965default

Non 2XX error response from server.

get/api/v2/tasksv2 API - 图966

/api/v2/tasks

Request samples

  • cURL: all tasks, basic output

Copy

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

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Example

Basic output

v2 API - 图967

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.

Copy

Expand all Collapse all

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

Create a task

Creates a task and returns the task.

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json

The task to create.

description
string

An optional description of the task.

flux
required
string

The Flux script to run for this task.

org
string

The name of the organization that owns this Task.

orgID
string

The ID of the organization that owns this Task.

status
string (TaskStatusType)
Enum: “active” “inactive”

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

Responses

v2 API - 图968201

Success. The response body contains a tasks list with the task.

v2 API - 图969400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed for org or orgID.

v2 API - 图970401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图971500

Internal server error. The server encountered an unexpected situation.

v2 API - 图972default

Unexpected error

post/api/v2/tasksv2 API - 图973

/api/v2/tasks

Request samples

  • Payload
  • cURL: create a task

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a task

Deletes a task and associated records.

Use this endpoint to delete a task and all associated records (task runs, logs, and labels). Once the task is deleted, InfluxDB cancels all scheduled runs of the task.

If you want to disable a task instead of delete it, update the task status to inactive.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to delete.

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

OpenTracing span context

Responses

204

Success. The task and runs are deleted. Scheduled runs are canceled.

v2 API - 图974400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图975401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图976404

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

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

v2 API - 图977500

Internal server error. The server encountered an unexpected situation.

v2 API - 图978default

Non 2XX error response from server.

delete/api/v2/tasks/{taskID}v2 API - 图979

/api/v2/tasks/{taskID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Retrieve a task

Retrieves a task.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to retrieve.

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

OpenTracing span context

Responses

v2 API - 图980200

Success. The response body contains the task.

v2 API - 图981400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图982401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图983404

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

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

v2 API - 图984500

Internal server error. The server encountered an unexpected situation.

v2 API - 图985default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}v2 API - 图986

/api/v2/tasks/{taskID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Update a task

Updates a task and then cancels all scheduled runs of the task.

Use this endpoint to set, modify, and clear task properties (for example: cron, name, flux, status). Once InfluxDB applies the update, it cancels all previously scheduled runs of the task.

To update a task, pass an object that contains the updated key-value pairs. To activate or inactivate a task, set the status property. "status": "inactive" cancels scheduled runs and prevents manual runs of the task.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to update.

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

OpenTracing span context

Request Body schema: application/json

An object that contains updated task properties to apply.

cron
string

Update the ‘cron’ option in the flux script.

description
string

Update the description of the task.

every
string

Update the ‘every’ option in the flux script.

flux
string

The Flux script that the task runs.

name
string

Update the ‘name’ option in the flux script.

offset
string

Update the ‘offset’ option in the flux script.

status
string (TaskStatusType)
Enum: “active” “inactive”

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

Responses

v2 API - 图987200

Success. The response body contains the updated task.

v2 API - 图988400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图989401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图990404

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

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

v2 API - 图991500

Internal server error. The server encountered an unexpected situation.

v2 API - 图992default

Non 2XX error response from server.

patch/api/v2/tasks/{taskID}v2 API - 图993

/api/v2/tasks/{taskID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "cron": "string", - "description": "string", - "every": "string", - "flux": "string", - "name": "string", - "offset": "string", - "status": "active" }

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

List labels for a task

Retrieves a list of all labels for a task.

Labels may be used for grouping and filtering tasks.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to retrieve labels for.

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

OpenTracing span context

Responses

v2 API - 图994200

Success. The response body contains a list of all labels for the task.

v2 API - 图995400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图996401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图997404

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

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

v2 API - 图998500

Internal server error. The server encountered an unexpected situation.

v2 API - 图999default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}/labelsv2 API - 图1000

/api/v2/tasks/{taskID}/labels

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a label to a task

Adds a label to a task.

Use this endpoint to add a label that you can use to filter tasks in the InfluxDB UI.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The ID of the task to label.

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

OpenTracing span context

Request Body schema: application/json

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

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图1001201

Success. The response body contains a list of all labels for the task.

v2 API - 图1002400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1003401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1004404

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

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

v2 API - 图1005500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1006default

Non 2XX error response from server.

post/api/v2/tasks/{taskID}/labelsv2 API - 图1007

/api/v2/tasks/{taskID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Delete a label from a task

Deletes a label from a task.

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The ID of the label to delete.

taskID
required
string

The ID of the task to delete the label from.

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

OpenTracing span context

Responses

204

Success. The label is deleted.

v2 API - 图1008400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1009401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1010404

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

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

v2 API - 图1011500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1012default

Non 2XX error response from server.

delete/api/v2/tasks/{taskID}/labels/{labelID}v2 API - 图1013

/api/v2/tasks/{taskID}/labels/{labelID}

Response samples

  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图1014200

Success. The response body contains an events list with logs for the task. Each log event message contains detail about the event. If a task run fails, InfluxDB logs an event with the reason for the failure.

v2 API - 图1015400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1016401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1017404

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

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

v2 API - 图1018500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1019default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}/logsv2 API - 图1020

/api/v2/tasks/{taskID}/logs

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Example

Events for a failed task run.

v2 API - 图1021

Events for a failed task run.

Events for a successful task run.

Copy

Expand all Collapse all

{ - "events": [ - { - "message": "Started task from script: \"option task = {name: \\\"test task\\\", every: 3d, offset: 0s}\"", - "runID": "09a946fc3167d000", - "time": "2022-07-13T07:06:54.198167Z" }, - { - "message": "Completed(failed)", - "runID": "09a946fc3167d000", - "time": "2022-07-13T07:07:13.104037Z" }, - { - "message": "error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a \"yield\" or invoking streaming functions directly, without performing an assignment", - "runID": "09a946fc3167d000", - "time": "2022-07-13T08:24:37.115323Z" } ] }

List all task members Deprecated

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations) to assign user permissions.

Lists all users that have the member role for the specified task.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The task ID.

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

OpenTracing span context

Responses

v2 API - 图1022200

Success. The response body contains a list of users that have the member role for a task.

v2 API - 图1023default

Unexpected error

get/api/v2/tasks/{taskID}/membersv2 API - 图1024

/api/v2/tasks/{taskID}/members

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add a member to a task Deprecated

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations) to assign user permissions.

Adds a user to members of a task and returns the member.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The task ID.

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

OpenTracing span context

Request Body schema: application/json

A user to add as a member of the task.

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图1025201

Created. The user is added to task members.

v2 API - 图1026default

Unexpected error

post/api/v2/tasks/{taskID}/membersv2 API - 图1027

/api/v2/tasks/{taskID}/members

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Remove a member from a task Deprecated

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations) to assign user permissions.

Removes a member from a task.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The task ID.

userID
required
string

The ID of the member to remove.

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

OpenTracing span context

Responses

204

Member removed

v2 API - 图1028default

Unexpected error

delete/api/v2/tasks/{taskID}/members/{userID}v2 API - 图1029

/api/v2/tasks/{taskID}/members/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图1030200

Success. The response contains a list of users that have the owner role for the task.

If the task has no owners, the response contains an empty users array.

v2 API - 图1031401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1032422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1033500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1034default

Unexpected error

get/api/v2/tasks/{taskID}/ownersv2 API - 图1035

/api/v2/tasks/{taskID}/owners

Response samples

  • 200
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Add an owner for a task Deprecated

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations) to assign user permissions.

Assigns a task owner role to a user.

Use this endpoint to create a resource owner for the task. A resource owner is a user with role: owner for a specific resource.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The task ID.

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

OpenTracing span context

Request Body schema: application/json

A user to add as an owner of the task.

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图1036201

Created. The task owner role is assigned to the user. The response body contains the resource owner with role and user detail.

v2 API - 图1037401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1038422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1039500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1040default

Unexpected error

post/api/v2/tasks/{taskID}/ownersv2 API - 图1041

/api/v2/tasks/{taskID}/owners

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "0772396d1f411000", - "links": { - "logs": "/api/v2/users/0772396d1f411000/logs", - "self": "/api/v2/users/0772396d1f411000" }, - "name": "USER_NAME", - "role": "owner", - "status": "active" }

Remove an owner from a task Deprecated

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations) to assign user permissions.

Authorizations:

TokenAuthentication

path Parameters
taskID
required
string

The task ID.

userID
required
string

The ID of the owner to remove.

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

OpenTracing span context

Responses

204

Owner removed

v2 API - 图1042default

Unexpected error

delete/api/v2/tasks/{taskID}/owners/{userID}v2 API - 图1043

/api/v2/tasks/{taskID}/owners/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图1044200

Success. The response body contains the list of task runs.

v2 API - 图1045401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1046500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1047default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}/runsv2 API - 图1048

/api/v2/tasks/{taskID}/runs

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Start a task run, overriding the schedule

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

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

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

Authorizations:

TokenAuthentication

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

OpenTracing span context

Request Body schema: application/json
scheduledFor
string or null <date-time>

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

Responses

v2 API - 图1049201

Success. The run is scheduled to start.

v2 API - 图1050401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1051500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1052default

Non 2XX error response from server.

post/api/v2/tasks/{taskID}/runsv2 API - 图1053

/api/v2/tasks/{taskID}/runs

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

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

Response samples

  • 201
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

Cancel a running task

Cancels a running task.

Use this endpoint with InfluxDB OSS to cancel a running task.

InfluxDB Cloud

  • Doesn’t support this operation.
Authorizations:

TokenAuthentication

path Parameters
runID
required
string

The ID of the task run to cancel.

taskID
required
string

The ID of the task to cancel.

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

OpenTracing span context

Responses

204

Success. The DELETE is accepted and the run will be cancelled.

InfluxDB Cloud

  • Doesn’t support this operation.
  • Doesn’t return this status.

v2 API - 图1054400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1055401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1056404

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

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

v2 API - 图1057405

Method not allowed.

InfluxDB Cloud

  • Always returns this error; doesn’t support cancelling tasks.

InfluxDB OSS

  • Doesn’t return this error.

v2 API - 图1058500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1059default

Non 2XX error response from server.

delete/api/v2/tasks/{taskID}/runs/{runID}v2 API - 图1060

/api/v2/tasks/{taskID}/runs/{runID}

Response samples

  • 400
  • 401
  • 404
  • 405
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

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

v2 API - 图1061200

Success. The response body contains the task run.

v2 API - 图1062400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1063401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1064404

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

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

v2 API - 图1065500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1066default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}/runs/{runID}v2 API - 图1067

/api/v2/tasks/{taskID}/runs/{runID}

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "finishedAt": "2022-07-18T14:46:07.308254Z", - "id": "09b070dadaa7d000", - "links": { - "logs": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/logs", - "retry": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000/retry", - "self": "/api/v2/tasks/0996e56b2f378000/runs/09b070dadaa7d000", - "task": "/api/v2/tasks/0996e56b2f378000" }, - "log": [ - { - "message": "Started task from script: \"option task = {name: \\\"task1\\\", every: 30m} from(bucket: \\\"iot_center\\\") |> range(start: -90d) |> filter(fn: (r) => r._measurement == \\\"environment\\\") |> aggregateWindow(every: 1h, fn: mean)\"", - "runID": "09b070dadaa7d000", - "time": "2022-07-18T14:46:07.101231Z" }, - { - "message": "Completed(success)", - "runID": "09b070dadaa7d000", - "time": "2022-07-18T14:46:07.242859Z" } ], - "requestedAt": "2022-07-18T14:46:06Z", - "scheduledFor": "2022-07-18T14:46:06Z", - "startedAt": "2022-07-18T14:46:07.16222Z", - "status": "success", - "taskID": "0996e56b2f378000" }

Retrieve all logs for a run

Retrieves all logs for a task run. A log is a list of run events with runID, time, and message properties.

Use this endpoint to help analyze task performance and troubleshoot failed task runs.

Authorizations:

TokenAuthentication

path Parameters
runID
required
string

The ID of the run to get logs for.

taskID
required
string

The ID of the task to get logs for.

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

OpenTracing span context

Responses

v2 API - 图1068200

Success. The response body contains an events list with logs for the task run. Each log event message contains detail about the event. If a run fails, InfluxDB logs an event with the reason for the failure.

v2 API - 图1069400

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

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1070401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1071404

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

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

v2 API - 图1072500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1073default

Non 2XX error response from server.

get/api/v2/tasks/{taskID}/runs/{runID}/logsv2 API - 图1074

/api/v2/tasks/{taskID}/runs/{runID}/logs

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Example

Events for a failed task.

v2 API - 图1075

Events for a failed task.

Events for a successful task run.

Copy

Expand all Collapse all

{ - "events": [ - { - "message": "Started task from script: \"option task = {name: \\\"test task\\\", every: 3d, offset: 0s}\"", - "runID": "09a946fc3167d000", - "time": "2022-07-13T07:06:54.198167Z" }, - { - "message": "Completed(failed)", - "runID": "09a946fc3167d000", - "time": "2022-07-13T07:07:13.104037Z" }, - { - "message": "error exhausting result iterator: error in query specification while starting program: this Flux script returns no streaming data. Consider adding a \"yield\" or invoking streaming functions directly, without performing an assignment", - "runID": "09a946fc3167d000", - "time": "2022-07-13T08:24:37.115323Z" } ] }

Retry a task run

Queues a task run to retry and returns the scheduled run.

To manually start a new task run, use the POST /api/v2/tasks/{taskID}/runs endpoint.

Limitations

  • The task must be active (status: "active").
Authorizations:

TokenAuthentication

path Parameters
runID
required
string

A task run ID. Specifies the task run to retry.

To find a task run ID, use the GET /api/v2/tasks/{taskID}/runs endpoint to list task runs.

taskID
required
string

A task ID. Specifies the task to retry.

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

OpenTracing span context

Request Body schema: application/json; charset=utf-8

object

Responses

v2 API - 图1076200

Success. The response body contains the queued run.

v2 API - 图1077400

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

InfluxDB may return this error for the following reasons:

  • The task has status: inactive.

v2 API - 图1078401

Unauthorized. The error may indicate one of the following:

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

v2 API - 图1079404

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

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.

v2 API - 图1080500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1081default

Non 2XX error response from server.

post/api/v2/tasks/{taskID}/runs/{runID}/retryv2 API - 图1082

/api/v2/tasks/{taskID}/runs/{runID}/retry

Request samples

  • Payload

Content type

application/json; charset=utf-8

Copy

Expand all Collapse all

{ }

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "09d60ffe08738000", - "links": { - "logs": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/logs", - "retry": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000/retry", - "self": "/api/v2/tasks/09a776832f381000/runs/09d60ffe08738000", - "task": "/api/v2/tasks/09a776832f381000" }, - "requestedAt": "2022-08-16T20:05:11.84145Z", - "scheduledFor": "2022-08-15T00:00:00Z", - "status": "scheduled", - "taskID": "09a776832f381000" }

Telegraf Plugins

List all Telegraf plugins

Authorizations:

TokenAuthentication

query Parameters
type
string

The type of plugin desired.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1083200

A list of Telegraf plugins.

v2 API - 图1084default

Unexpected error

get/api/v2/telegraf/pluginsv2 API - 图1085

/api/v2/telegraf/plugins

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "os": "string", - "plugins": [ - { - "config": "string", - "description": "string", - "name": "string", - "type": "string" } ], - "version": "string" }

Telegrafs

List all Telegraf configurations

Authorizations:

TokenAuthentication

query Parameters
orgID
string

The organization ID the Telegraf config belongs to.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1086200

A list of Telegraf configurations

v2 API - 图1087default

Unexpected error

get/api/v2/telegrafsv2 API - 图1088

/api/v2/telegrafs

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "configurations": [ - { - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/telegrafs/1/labels", - "members": "/api/v2/telegrafs/1/members", - "owners": "/api/v2/telegrafs/1/owners", - "self": "/api/v2/telegrafs/1" } } ] }

Create a Telegraf configuration

Authorizations:

TokenAuthentication

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Telegraf configuration to create

config
string
description
string
object
name
string
orgID
string
Array of objects

Responses

v2 API - 图1091201

Telegraf configuration created

v2 API - 图1092default

Unexpected error

post/api/v2/telegrafsv2 API - 图1093

/api/v2/telegrafs

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "plugins": [ - { - "alias": "string", - "config": "string", - "description": "string", - "name": "string", - "type": "string" } ] }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/telegrafs/1/labels", - "members": "/api/v2/telegrafs/1/members", - "owners": "/api/v2/telegrafs/1/owners", - "self": "/api/v2/telegrafs/1" } }

Delete a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf configuration ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图1094default

Unexpected error

delete/api/v2/telegrafs/{telegrafID}v2 API - 图1095

/api/v2/telegrafs/{telegrafID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1096200

Telegraf configuration details

v2 API - 图1097default

Unexpected error

get/api/v2/telegrafs/{telegrafID}v2 API - 图1098

/api/v2/telegrafs/{telegrafID}

Response samples

  • 200
  • default

Content type

application/json

v2 API - 图1099

application/json

application/octet-stream

application/toml

Copy

Expand all Collapse all

{ - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/telegrafs/1/labels", - "members": "/api/v2/telegrafs/1/members", - "owners": "/api/v2/telegrafs/1/owners", - "self": "/api/v2/telegrafs/1" } }

Update a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Telegraf configuration update to apply

config
string
description
string
object
name
string
orgID
string
Array of objects

Responses

v2 API - 图1102200

An updated Telegraf configurations

v2 API - 图1103default

Unexpected error

put/api/v2/telegrafs/{telegrafID}v2 API - 图1104

/api/v2/telegrafs/{telegrafID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "plugins": [ - { - "alias": "string", - "config": "string", - "description": "string", - "name": "string", - "type": "string" } ] }

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/telegrafs/1/labels", - "members": "/api/v2/telegrafs/1/members", - "owners": "/api/v2/telegrafs/1/owners", - "self": "/api/v2/telegrafs/1" } }

List all labels for a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1105200

A list of all labels for a Telegraf config

v2 API - 图1106default

Unexpected error

get/api/v2/telegrafs/{telegrafID}/labelsv2 API - 图1107

/api/v2/telegrafs/{telegrafID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "next": "[http://example.com](http://example.com)", - "prev": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" } }

Add a label to a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图1108201

The label added to the Telegraf config

v2 API - 图1109default

Unexpected error

post/api/v2/telegrafs/{telegrafID}/labelsv2 API - 图1110

/api/v2/telegrafs/{telegrafID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "label": { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } }, - "links": { - "next": "[http://example.com](http://example.com)", - "prev": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" } }

Delete a label from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The label ID.

telegrafID
required
string

The Telegraf config ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图1111404

Telegraf config not found

v2 API - 图1112default

Unexpected error

delete/api/v2/telegrafs/{telegrafID}/labels/{labelID}v2 API - 图1113

/api/v2/telegrafs/{telegrafID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1114200

A list of Telegraf config members

v2 API - 图1115default

Unexpected error

get/api/v2/telegrafs/{telegrafID}/membersv2 API - 图1116

/api/v2/telegrafs/{telegrafID}/members

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "links": { - "self": "[http://example.com](http://example.com)" }, - "users": [ - { - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active", - "role": "member" } ] }

Add a member to a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as member

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图1117201

Member added to Telegraf config

v2 API - 图1118default

Unexpected error

post/api/v2/telegrafs/{telegrafID}/membersv2 API - 图1119

/api/v2/telegrafs/{telegrafID}/members

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "name": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active", - "role": "member" }

Remove a member from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

userID
required
string

The ID of the member to remove.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Member removed

v2 API - 图1120default

Unexpected error

delete/api/v2/telegrafs/{telegrafID}/members/{userID}v2 API - 图1121

/api/v2/telegrafs/{telegrafID}/members/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1122200

Returns Telegraf configuration owners as a ResourceOwners list

v2 API - 图1123default

Unexpected error

get/api/v2/telegrafs/{telegrafID}/ownersv2 API - 图1124

/api/v2/telegrafs/{telegrafID}/owners

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "links": { - "self": "[http://example.com](http://example.com)" }, - "users": [ - { - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active", - "role": "owner" } ] }

Add an owner to a Telegraf configuration

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf configuration ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

User to add as owner

id
required
string

The ID of the user to add to the resource.

name
string

The name of the user to add to the resource.

Responses

v2 API - 图1125201

Telegraf configuration owner was added. Returns a ResourceOwner that references the User.

v2 API - 图1126default

Unexpected error

post/api/v2/telegrafs/{telegrafID}/ownersv2 API - 图1127

/api/v2/telegrafs/{telegrafID}/owners

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "name": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active", - "role": "owner" }

Remove an owner from a Telegraf config

Authorizations:

TokenAuthentication

path Parameters
telegrafID
required
string

The Telegraf config ID.

userID
required
string

The ID of the owner to remove.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Owner removed

v2 API - 图1128default

Unexpected error

delete/api/v2/telegrafs/{telegrafID}/owners/{userID}v2 API - 图1129

/api/v2/telegrafs/{telegrafID}/owners/{userID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "code": "internal error", - "err": "string", - "message": "string", - "op": "string" }

Templates

Export and apply InfluxDB templates. Manage stacks of templated InfluxDB resources.

InfluxDB templates are prepackaged configurations for everything from dashboards and Telegraf to notifications and alerts. Use InfluxDB templates to quickly configure a fresh instance of InfluxDB, back up your dashboard configuration, or share your configuration with the InfluxData community.

Use the /api/v2/templates endpoints to export templates and apply templates.

InfluxDB stacks are stateful InfluxDB templates that let you add, update, and remove installed template resources over time, avoid duplicating resources when applying the same or similar templates more than once, and apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.

Use the /api/v2/stacks endpoints to manage installed template resources.

List installed stacks

Lists installed InfluxDB stacks.

To limit stacks in the response, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all installed stacks for the organization.

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

v2 API - 图1130200

Success. The response body contains the list of stacks.

v2 API - 图1131400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1132401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1133500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1134default

Unexpected error

get/api/v2/stacksv2 API - 图1135

/api/v2/stacks

Response samples

  • 200
  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "stacks": [ - { - "createdAt": "2019-08-24T14:15:22Z", - "events": [ - { - "description": "string", - "eventType": "string", - "name": "string", - "resources": [ - { - "apiVersion": "string", - "associations": [ - { - "kind": "Bucket", - "metaName": "string" } ], - "kind": "Bucket", - "links": { - "self": "string" }, - "resourceID": "string", - "templateMetaName": "string" } ], - "sources": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z", - "urls": [ - "string" ] } ], - "id": "string", - "orgID": "string" } ] }

Create a stack

Creates or initializes a stack.

Use this endpoint to manually initialize a new stack with the following optional information:

  • Stack name
  • Stack description
  • URLs for template manifest files

To automatically create a stack when applying templates, use the /api/v2/templates/apply endpoint.

Required permissions

  • write permission for the organization
Authorizations:

TokenAuthentication

Request Body schema: application/json

The stack to create.

description
string
name
string
orgID
string
urls
Array of strings

Responses

v2 API - 图1136201

Success. Returns the newly created stack.

v2 API - 图1137401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1138422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1139500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1140default

Unexpected error

post/api/v2/stacksv2 API - 图1141

/api/v2/stacks

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "description": "string", - "name": "string", - "orgID": "string", - "urls": [ - "string" ] }

Response samples

  • 201
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "createdAt": "2019-08-24T14:15:22Z", - "events": [ - { - "description": "string", - "eventType": "string", - "name": "string", - "resources": [ - { - "apiVersion": "string", - "associations": [ - { - "kind": "Bucket", - "metaName": "string" } ], - "kind": "Bucket", - "links": { - "self": "string" }, - "resourceID": "string", - "templateMetaName": "string" } ], - "sources": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z", - "urls": [ - "string" ] } ], - "id": "string", - "orgID": "string" }

Delete a stack and associated resources

Authorizations:

TokenAuthentication

path Parameters
stack_id
required
string

The identifier of the stack.

query Parameters
orgID
required
string

The identifier of the organization.

Responses

204

The stack and its associated resources were deleted.

v2 API - 图1142default

Unexpected error

delete/api/v2/stacks/{stack_id}v2 API - 图1143

/api/v2/stacks/{stack_id}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1144200

Returns the stack.

v2 API - 图1145default

Unexpected error

get/api/v2/stacks/{stack_id}v2 API - 图1146

/api/v2/stacks/{stack_id}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "createdAt": "2019-08-24T14:15:22Z", - "events": [ - { - "description": "string", - "eventType": "string", - "name": "string", - "resources": [ - { - "apiVersion": "string", - "associations": [ - { - "kind": "Bucket", - "metaName": "string" } ], - "kind": "Bucket", - "links": { - "self": "string" }, - "resourceID": "string", - "templateMetaName": "string" } ], - "sources": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z", - "urls": [ - "string" ] } ], - "id": "string", - "orgID": "string" }

Update a stack

Authorizations:

TokenAuthentication

path Parameters
stack_id
required
string

The identifier of the stack.

Request Body schema: application/json

The stack to update.

Array of objects
description
string or null
name
string or null
templateURLs
Array of strings or null

Responses

v2 API - 图1148200

Returns the updated stack.

v2 API - 图1149default

Unexpected error

patch/api/v2/stacks/{stack_id}v2 API - 图1150

/api/v2/stacks/{stack_id}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "additionalResources": [ - { - "kind": "string", - "resourceID": "string", - "templateMetaName": "string" } ], - "description": "string", - "name": "string", - "templateURLs": [ - "string" ] }

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "createdAt": "2019-08-24T14:15:22Z", - "events": [ - { - "description": "string", - "eventType": "string", - "name": "string", - "resources": [ - { - "apiVersion": "string", - "associations": [ - { - "kind": "Bucket", - "metaName": "string" } ], - "kind": "Bucket", - "links": { - "self": "string" }, - "resourceID": "string", - "templateMetaName": "string" } ], - "sources": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z", - "urls": [ - "string" ] } ], - "id": "string", - "orgID": "string" }

Uninstall a stack

Authorizations:

TokenAuthentication

path Parameters
stack_id
required
string

The identifier of the stack.

Responses

v2 API - 图1151200

Returns the uninstalled stack.

v2 API - 图1152default

Unexpected error

post/api/v2/stacks/{stack_id}/uninstallv2 API - 图1153

/api/v2/stacks/{stack_id}/uninstall

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "createdAt": "2019-08-24T14:15:22Z", - "events": [ - { - "description": "string", - "eventType": "string", - "name": "string", - "resources": [ - { - "apiVersion": "string", - "associations": [ - { - "kind": "Bucket", - "metaName": "string" } ], - "kind": "Bucket", - "links": { - "self": "string" }, - "resourceID": "string", - "templateMetaName": "string" } ], - "sources": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z", - "urls": [ - "string" ] } ], - "id": "string", - "orgID": "string" }

Apply or dry-run a template

Applies a template to create or update a stack of InfluxDB resources. The response contains the diff of changes and the stack ID.

Use this endpoint to install an InfluxDB template to an organization. Provide template URLs or template objects in your request. To customize which template resources are installed, use the actions parameter.

By default, when you apply a template, InfluxDB installs the template to create and update stack resources and then generates a diff of the changes. If you pass dryRun: true in the request body, InfluxDB validates the template and generates the resource diff, but doesn’t make any changes to your instance.

Custom values for templates

Required permissions

  • write permissions for resource types in the template.

Rate limits (with InfluxDB Cloud)

Authorizations:

TokenAuthentication

Request Body schema:

application/json

v2 API - 图1154

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:

  1. import “sql”
  2. import “influxdata/influxdb/secrets”
  4. username = secrets.get(key: “POSTGRES_USERNAME”)
  5. password = secrets.get(key: “POSTGRES_PASSWORD”)
  7. sql.from(
  8.   driverName: “postgres”,
  9.   dataSourceName: “postgresql://${username}:${password}@localhost:5432”,
  10.   query: “SELECT * FROM example_table”,
  11. )

To define secret values in your /api/v2/templates/apply request, pass the secrets parameter with key-value pairs—for example:

  1. {
  2.   …
  3.   “secrets”: {
  4.     “POSTGRES_USERNAME”: “pguser”,
  5.     “POSTGRES_PASSWORD”: “foo”
  6.   }
  7.   …
  8. }

InfluxDB stores the key-value pairs as secrets that you can access with secrets.get(). Once stored, you can’t view secret values in InfluxDB.

Related guides

stackID
string

ID of the stack to update.

To apply templates to an existing stack in the organization, use the stackID parameter. If you apply templates without providing a stack ID, InfluxDB initializes a new stack with all new resources.

To find a stack ID, use the InfluxDB /api/v2/stacks API endpoint to list stacks.

Related guides

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

v2 API - 图1161200

Success. The template dry run succeeded. The response body contains a resource diff of changes that the template would have made if installed. No resources were created or updated. The diff and summary won’t contain IDs for resources that didn’t exist at the time of the dry run.

v2 API - 图1162201

Success. The template applied successfully. The response body contains the stack ID, a diff, and a summary. The diff compares the initial state to the state after the template installation. The summary contains newly created resources.

v2 API - 图1163422

Unprocessable entity.

The error may indicate one of the following problems:

  • The template failed validation.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1164500

Internal server error.

InfluxDB Cloud

  • Returns this error if creating one of the template resources (bucket, dashboard, task, user) exceeds your plan’s adjustable service quotas.

v2 API - 图1165default

Unexpected error

post/api/v2/templates/applyv2 API - 图1166

/api/v2/templates/apply

Request samples

  • Payload
  • cURL: Dry run with a remote template
  • cURL: Apply with secret values
  • cURL: Apply template objects with environment references

Content type

application/json

v2 API - 图1167

application/json

application/x-jsonnet

text/yml

Example

Skip all bucket and task resources in the provided templates

v2 API - 图1168

Skip all bucket and task resources in the provided templates

Skip specific resources in the provided templates

envRefs for template objects

Copy

Expand all Collapse all

{ - "actions": [ - { - "action": "skipKind", - "properties": { - "kind": "Bucket" } }, - { - "action": "skipKind", - "properties": { - "kind": "Task" } } ], - "orgID": "INFLUX_ORG_ID", - "templates": [ - { - "contents": [ - { - "[object Object]": null } ] } ] }

Response samples

  • 200
  • 201
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "diff": { - "buckets": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "description": "string", - "name": "string", - "retentionRules": [ - { - "everySeconds": 86400, - "shardGroupDurationSeconds": 0, - "type": "expire" } ] }, - "old": { - "description": "string", - "name": "string", - "retentionRules": [ - { - "everySeconds": 86400, - "shardGroupDurationSeconds": 0, - "type": "expire" } ] }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "checks": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "lastRunError": "string", - "lastRunStatus": "failed", - "latestCompleted": "2019-08-24T14:15:22Z", - "links": { - "labels": "/api/v2/checks/1/labels", - "members": "/api/v2/checks/1/members", - "owners": "/api/v2/checks/1/owners", - "query": "/api/v2/checks/1/query", - "self": "/api/v2/checks/1" }, - "name": "string", - "orgID": "string", - "ownerID": "string", - "query": { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - null ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" }, - "status": "active", - "taskID": "string", - "updatedAt": "2019-08-24T14:15:22Z", - "every": "string", - "level": "UNKNOWN", - "offset": "string", - "reportZero": true, - "staleTime": "string", - "statusMessageTemplate": "string", - "tags": [ - { - "key": "string", - "value": "string" } ], - "timeSince": "string", - "type": "deadman" }, - "old": { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "lastRunError": "string", - "lastRunStatus": "failed", - "latestCompleted": "2019-08-24T14:15:22Z", - "links": { - "labels": "/api/v2/checks/1/labels", - "members": "/api/v2/checks/1/members", - "owners": "/api/v2/checks/1/owners", - "query": "/api/v2/checks/1/query", - "self": "/api/v2/checks/1" }, - "name": "string", - "orgID": "string", - "ownerID": "string", - "query": { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - null ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" }, - "status": "active", - "taskID": "string", - "updatedAt": "2019-08-24T14:15:22Z", - "every": "string", - "level": "UNKNOWN", - "offset": "string", - "reportZero": true, - "staleTime": "string", - "statusMessageTemplate": "string", - "tags": [ - { - "key": "string", - "value": "string" } ], - "timeSince": "string", - "type": "deadman" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "dashboards": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "charts": [ - { - "height": 0, - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": null, - "bounds": [ ], - "label": null, - "prefix": null, - "scale": null, - "suffix": null }, - "y": { - "base": null, - "bounds": [ ], - "label": null, - "prefix": null, - "scale": null, - "suffix": null } }, - "colors": [ - { - "hex": null, - "id": null, - "name": null, - "type": null, - "value": null } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": null, - "editMode": null, - "name": null, - "text": null } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 }, - "width": 0, - "xPos": 0, - "yPos": 0 } ], - "description": "string", - "name": "string" }, - "old": { - "charts": [ - { - "height": 0, - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": null, - "bounds": [ ], - "label": null, - "prefix": null, - "scale": null, - "suffix": null }, - "y": { - "base": null, - "bounds": [ ], - "label": null, - "prefix": null, - "scale": null, - "suffix": null } }, - "colors": [ - { - "hex": null, - "id": null, - "name": null, - "type": null, - "value": null } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": null, - "editMode": null, - "name": null, - "text": null } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 }, - "width": 0, - "xPos": 0, - "yPos": 0 } ], - "description": "string", - "name": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "labelMappings": [ - { - "labelID": "string", - "labelName": "string", - "labelTemplateMetaName": "string", - "resourceID": "string", - "resourceName": "string", - "resourceTemplateMetaName": "string", - "resourceType": "string", - "status": "string" } ], - "labels": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "color": "string", - "description": "string", - "name": "string" }, - "old": { - "color": "string", - "description": "string", - "name": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "notificationEndpoints": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/notificationEndpoints/1/labels", - "members": "/api/v2/notificationEndpoints/1/members", - "owners": "/api/v2/notificationEndpoints/1/owners", - "self": "/api/v2/notificationEndpoints/1" }, - "name": "string", - "orgID": "string", - "status": "active", - "type": "slack", - "updatedAt": "2019-08-24T14:15:22Z", - "userID": "string", - "token": "string", - "url": "string" }, - "old": { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/notificationEndpoints/1/labels", - "members": "/api/v2/notificationEndpoints/1/members", - "owners": "/api/v2/notificationEndpoints/1/owners", - "self": "/api/v2/notificationEndpoints/1" }, - "name": "string", - "orgID": "string", - "status": "active", - "type": "slack", - "updatedAt": "2019-08-24T14:15:22Z", - "userID": "string", - "token": "string", - "url": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "notificationRules": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "description": "string", - "endpointID": "string", - "endpointName": "string", - "endpointType": "string", - "every": "string", - "messageTemplate": "string", - "name": "string", - "offset": "string", - "status": "string", - "statusRules": [ - { - "currentLevel": "string", - "previousLevel": "string" } ], - "tagRules": [ - { - "key": "string", - "operator": "string", - "value": "string" } ] }, - "old": { - "description": "string", - "endpointID": "string", - "endpointName": "string", - "endpointType": "string", - "every": "string", - "messageTemplate": "string", - "name": "string", - "offset": "string", - "status": "string", - "statusRules": [ - { - "currentLevel": "string", - "previousLevel": "string" } ], - "tagRules": [ - { - "key": "string", - "operator": "string", - "value": "string" } ] }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "tasks": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "cron": "string", - "description": "string", - "every": "string", - "name": "string", - "offset": "string", - "query": "string", - "status": "string" }, - "old": { - "cron": "string", - "description": "string", - "every": "string", - "name": "string", - "offset": "string", - "query": "string", - "status": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "telegrafConfigs": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string" }, - "old": { - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ], - "variables": [ - { - "id": "string", - "kind": "Bucket", - "new": { - "args": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "description": "string", - "name": "string" }, - "old": { - "args": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "description": "string", - "name": "string" }, - "stateStatus": "string", - "templateMetaName": "string" } ] }, - "errors": [ - { - "fields": [ - "string" ], - "indexes": [ - 0 ], - "kind": "Bucket", - "reason": "string" } ], - "sources": [ - "string" ], - "stackID": "string", - "summary": { - "buckets": [ - { - "description": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "name": "string", - "orgID": "string", - "retentionPeriod": 0, - "templateMetaName": "string" } ], - "checks": [ - { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "lastRunError": "string", - "lastRunStatus": "failed", - "latestCompleted": "2019-08-24T14:15:22Z", - "links": { - "labels": "/api/v2/checks/1/labels", - "members": "/api/v2/checks/1/members", - "owners": "/api/v2/checks/1/owners", - "query": "/api/v2/checks/1/query", - "self": "/api/v2/checks/1" }, - "name": "string", - "orgID": "string", - "ownerID": "string", - "query": { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - "string" ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" }, - "status": "active", - "taskID": "string", - "updatedAt": "2019-08-24T14:15:22Z", - "every": "string", - "level": "UNKNOWN", - "offset": "string", - "reportZero": true, - "staleTime": "string", - "statusMessageTemplate": "string", - "tags": [ - { - "key": "string", - "value": "string" } ], - "timeSince": "string", - "type": "deadman", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "templateMetaName": "string" } ], - "dashboards": [ - { - "charts": [ - { - "height": 0, - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": "", - "bounds": [ - null ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" }, - "y": { - "base": "", - "bounds": [ - null ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" } }, - "colors": [ - { - "hex": "strings", - "id": "string", - "name": "string", - "type": "min", - "value": 0 } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": { - "aggregateWindow": { }, - "buckets": [ ], - "functions": [ ], - "tags": [ ] }, - "editMode": "builder", - "name": "string", - "text": "string" } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 }, - "width": 0, - "xPos": 0, - "yPos": 0 } ], - "description": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "name": "string", - "orgID": "string", - "templateMetaName": "string" } ], - "labelMappings": [ - { - "labelID": "string", - "labelName": "string", - "labelTemplateMetaName": "string", - "resourceID": "string", - "resourceName": "string", - "resourceTemplateMetaName": "string", - "resourceType": "string", - "status": "string" } ], - "labels": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "missingEnvRefs": [ - "string" ], - "missingSecrets": [ - "string" ], - "notificationEndpoints": [ - { - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "/api/v2/notificationEndpoints/1/labels", - "members": "/api/v2/notificationEndpoints/1/members", - "owners": "/api/v2/notificationEndpoints/1/owners", - "self": "/api/v2/notificationEndpoints/1" }, - "name": "string", - "orgID": "string", - "status": "active", - "type": "slack", - "updatedAt": "2019-08-24T14:15:22Z", - "userID": "string", - "token": "string", - "url": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "templateMetaName": "string" } ], - "notificationRules": [ - { - "description": "string", - "endpointID": "string", - "endpointTemplateMetaName": "string", - "endpointType": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "every": "string", - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "messageTemplate": "string", - "name": "string", - "offset": "string", - "status": "string", - "statusRules": [ - { - "currentLevel": "string", - "previousLevel": "string" } ], - "tagRules": [ - { - "key": "string", - "operator": "string", - "value": "string" } ], - "templateMetaName": "string" } ], - "tasks": [ - { - "cron": "string", - "description": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "every": "string", - "id": "string", - "kind": "Bucket", - "name": "string", - "offset": "string", - "query": "string", - "status": "string", - "templateMetaName": "string" } ], - "telegrafConfigs": [ - { - "config": "string", - "description": "string", - "metadata": { - "buckets": [ - "string" ] }, - "name": "string", - "orgID": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "templateMetaName": "string" } ], - "variables": [ - { - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "description": "string", - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "labelAssociations": [ - { - "envReferences": [ - { - "defaultValue": "string", - "envRefKey": "string", - "resourceField": "string", - "value": "string" } ], - "id": "string", - "kind": "Bucket", - "name": "string", - "orgID": "string", - "properties": { - "color": "string", - "description": "string" }, - "templateMetaName": "string" } ], - "name": "string", - "orgID": "string", - "templateMetaName": "string" } ] } }

Export a new template

Authorizations:

TokenAuthentication

Request Body schema: application/json

Export resources as an InfluxDB template.

One of

TemplateExportByIDTemplateExportByName

Array of objects
Array of objects
stackID
string

Responses

v2 API - 图1171200

The template was created successfully. Returns the newly created template.

v2 API - 图1172default

Unexpected error

post/api/v2/templates/exportv2 API - 图1173

/api/v2/templates/export

Request samples

  • Payload

Content type

application/json

Example

TemplateExportByID

v2 API - 图1174

TemplateExportByID

TemplateExportByName

Copy

Expand all Collapse all

{ - "orgIDs": [ - { - "orgID": "string", - "resourceFilters": { - "byLabel": [ - "string" ], - "byResourceKind": [ - "Bucket" ] } } ], - "resources": [ - { - "id": "string", - "kind": "Bucket", - "name": "string" } ], - "stackID": "string" }

Response samples

  • 200
  • default

Content type

application/json

v2 API - 图1175

application/json

application/x-yaml

Copy

Expand all Collapse all

[ - { - "apiVersion": "influxdata.com/v2alpha1", - "kind": "Bucket", - "metadata": { - "name": "string" }, - "spec": { } } ]

Users

Manage users for your organization. Users are those with access to InfluxDB. To grant a user permission to access data, add them as a member of an organization and provide them with an API token.

User sessions with authorizations

Optionally, you can scope an authorization (and its API token) to a user. If a user signs in with username and password, creating a user session, the session carries the permissions granted by all the user’s authorizations. To create a user session, use the POST /api/v2/signin endpoint.

Retrieve the currently authenticated user

Authorizations:

TokenAuthentication

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1176200

Success. The response body contains the currently authenticated user.

v2 API - 图1177401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1178500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1179default

Non 2XX error response from server.

get/api/v2/mev2 API - 图1180

/api/v2/me

Response samples

  • 200
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" }

Update a password

Updates the password for the signed-in user.

This endpoint represents the third step in the following three-step process to let a user with a user session update their password:

  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

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.

Related guides

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

204

Success. The password is updated.

400

Bad request.

InfluxDB Cloud

  • Doesn’t let you manage user passwords through the API; always responds with this status.

InfluxDB OSS

  • Doesn’t understand a value passed in the request.

v2 API - 图1181401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1182default

Unsuccessful authentication

put/api/v2/me/passwordv2 API - 图1183

/api/v2/me/password

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • 401
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "code": "unauthorized", - "message": "unauthorized access" }

List users

Lists users. Default limit is 20.

To limit which users are returned, pass query parameters in your request.

Required permissions for InfluxDB OSS

ActionPermission requiredRestriction
List all usersOperator token
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
after
string

A resource ID to seek from. Returns records created after the specified record; results don’t include the specified record.

Use after instead of the offset parameter. For more information about pagination parameters, see Pagination.

id
string

A user ID. Only lists the specified user.

limit
integer [ 1 .. 100 ]
Default: 20

Limits the number of records returned. Default is 20.

name
string

A user name. Only lists the specified user.

offset
integer >= 0

The offset for pagination. The number of records to skip.

For more information about pagination parameters, see Pagination.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1184200

Success. The response contains a list of users.

v2 API - 图1185401

Unauthorized.

v2 API - 图1186422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1187500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1188default

Non 2XX error response from server.

get/api/v2/usersv2 API - 图1189

/api/v2/users

Response samples

  • 200
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "links": { - "self": "[http://example.com](http://example.com)" }, - "users": [ - { - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" } ] }

Create a user

Creates a user that can access InfluxDB. Returns the user.

Use this endpoint to create a user that can sign in to start a user session through one of the following interfaces:

  • InfluxDB UI
  • /api/v2/signin InfluxDB API endpoint
  • InfluxDB CLI

This endpoint represents the first two steps in a four-step process to allow a user to authenticate with a username and password, and then access data in an organization:

  1. Create a user: send a POST request to POST /api/v2/users. The name property is required.
  2. Extract the user ID (id property) value from the API response for step 1.
  3. Create an authorization (and API token) for the user: send a POST request to POST /api/v2/authorizations, passing the user ID (id) from step 2.
  4. Create a password for the user: send a POST request to POST /api/v2/users/USER_ID/password, passing the user ID from step 2.

Required permissions

ActionPermission requiredRestriction
Create a userOperator token
Authorizations:

TokenAuthentication

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The user to create.

name
required
string

The user name.

status
string
Default: “active”
Enum: “active” “inactive”

If inactive, the user is inactive. Default is active.

Responses

v2 API - 图1190201

Success. The response body contains the user.

v2 API - 图1191401

Unauthorized.

v2 API - 图1192422

Unprocessable entity.

The error may indicate one of the following problems:

  • The request body isn’t valid—the request is well-formed, but InfluxDB can’t process it due to semantic errors.
  • You passed a parameter combination that InfluxDB doesn’t support.

v2 API - 图1193500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1194default

Non 2XX error response from server.

post/api/v2/usersv2 API - 图1195

/api/v2/users

Request samples

  • Payload
  • cURL: create a user and set a password

Content type

application/json

Copy

Expand all Collapse all

{ - "name": "string", - "status": "active" }

Response samples

  • 201
  • 401
  • 422
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" }

Delete a user

Deletes a user.

Required permissions

ActionPermission required
Delete a userwrite-users or write-user USER_ID

USER_ID is the ID of the user that you want to delete.

Authorizations:

TokenAuthentication

path Parameters
userID
required
string

A user ID. Specifies the user to delete.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Success. The user is deleted.

v2 API - 图1196400

Bad request. The response body contains detail about the error.

v2 API - 图1197401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1198500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1199default

Non 2XX error response from server.

delete/api/v2/users/{userID}v2 API - 图1200

/api/v2/users/{userID}

Response samples

  • 400
  • 401
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "code": "internal error", - "err": "string", - "message": "string", - "op": "string" }

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

v2 API - 图1201200

Success. The response body contains the user.

v2 API - 图1202default

Non 2XX error response from server.

get/api/v2/users/{userID}v2 API - 图1203

/api/v2/users/{userID}

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" }

Update a user

Updates a user and returns the user.

Required permissions

ActionPermission required
Update a userwrite-users or write-user USER_ID

USER_ID is the ID of the user that you want to update.

Authorizations:

TokenAuthentication

path Parameters
userID
required
string

A user ID. Specifies the user to update.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

In the request body, provide the user properties to update.

name
required
string

The user name.

status
string
Default: “active”
Enum: “active” “inactive”

If inactive, the user is inactive. Default is active.

Responses

v2 API - 图1204200

Success. The response body contains the user.

v2 API - 图1205400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.

v2 API - 图1206401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1207404

Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)—for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.

v2 API - 图1208500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1209default

Non 2XX error response from server.

patch/api/v2/users/{userID}v2 API - 图1210

/api/v2/users/{userID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "name": "string", - "status": "active" }

Response samples

  • 200
  • 400
  • 401
  • 404
  • 500
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "/api/v2/users/1" }, - "name": "string", - "status": "active" }

Update a password

Updates a user password.

InfluxDB Cloud

  • Doesn’t allow you to manage user passwords through the API. Use the InfluxDB Cloud user interface (UI) to update a password.
Authorizations:

TokenAuthentication

path Parameters
userID
required
string

The ID of the user to set the password for.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

The new password to set for the user.

password
required
string

Responses

204

Success. The password is updated.

v2 API - 图1211400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS

  • Doesn’t understand a value passed in the request.

v2 API - 图1212default

Non 2XX error response from server.

post/api/v2/users/{userID}/passwordv2 API - 图1213

/api/v2/users/{userID}/password

Request samples

  • Payload
  • cURL: use HTTP POST to update the user password

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

204

Success. The password is updated.

v2 API - 图1214400

Bad request.

InfluxDB Cloud

  • Doesn’t allow you to manage passwords through the API; always responds with this status.

InfluxDB OSS

  • Doesn’t understand a value passed in the request.

v2 API - 图1215default

Non 2XX error response from server.

put/api/v2/users/{userID}/passwordv2 API - 图1216

/api/v2/users/{userID}/password

Request samples

  • Payload
  • cURL: use Basic auth to update the user password

Content type

application/json

Copy

Expand all Collapse all

{ - "password": "string" }

Response samples

  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1217200

A list of variables for an organization

v2 API - 图1218400

Non 2XX error response from server.

v2 API - 图1219default

Non 2XX error response from server.

get/api/v2/variablesv2 API - 图1220

/api/v2/variables

Response samples

  • 200
  • 400
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "variables": [ - { - "arguments": { - "type": "constant", - "values": [ - "howdy", - "hello", - "hi", - "yo", - "oy" ] }, - "id": "1221432", - "name": ":ok:", - "selected": [ - "hello" ] }, - { - "arguments": { - "type": "map", - "values": { - "a": "fdjaklfdjkldsfjlkjdsa", - "b": "dfaksjfkljekfajekdljfas", - "c": "fdjksajfdkfeawfeea" } }, - "id": "1221432", - "name": ":ok:", - "selected": [ - "c" ] }, - { - "arguments": { - "language": "flux", - "query": "from(bucket: \"foo\") |> showMeasurements()", - "type": "query" }, - "id": "1221432", - "name": ":ok:", - "selected": [ - "host" ] } ] }

Create a variable

Authorizations:

TokenAuthentication

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable to create

required
QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt
string <date-time>
description
string
Array of objects (Labels)
name
required
string
orgID
required
string
selected
Array of strings
updatedAt
string <date-time>

Responses

v2 API - 图1223201

Variable created

v2 API - 图1224default

Non 2XX error response from server.

post/api/v2/variablesv2 API - 图1225

/api/v2/variables

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "labels": [ - { - "name": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "[http://example.com](http://example.com)", - "org": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" }, - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Delete a variable

Authorizations:

TokenAuthentication

path Parameters
variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Variable deleted

v2 API - 图1226default

Non 2XX error response from server.

delete/api/v2/variables/{variableID}v2 API - 图1227

/api/v2/variables/{variableID}

Response samples

  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1228200

Variable found

v2 API - 图1229404

Non 2XX error response from server.

v2 API - 图1230default

Non 2XX error response from server.

get/api/v2/variables/{variableID}v2 API - 图1231

/api/v2/variables/{variableID}

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "[http://example.com](http://example.com)", - "org": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" }, - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Update a variable

Authorizations:

TokenAuthentication

path Parameters
variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable update to apply

required
QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt
string <date-time>
description
string
Array of objects (Labels)
name
required
string
orgID
required
string
selected
Array of strings
updatedAt
string <date-time>

Responses

v2 API - 图1234200

Variable updated

v2 API - 图1235default

Non 2XX error response from server.

patch/api/v2/variables/{variableID}v2 API - 图1236

/api/v2/variables/{variableID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "labels": [ - { - "name": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "[http://example.com](http://example.com)", - "org": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" }, - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Replace a variable

Authorizations:

TokenAuthentication

path Parameters
variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Variable to replace

required
QueryVariableProperties (object) or ConstantVariableProperties (object) or MapVariableProperties (object) (VariableProperties)
createdAt
string <date-time>
description
string
Array of objects (Labels)
name
required
string
orgID
required
string
selected
Array of strings
updatedAt
string <date-time>

Responses

v2 API - 图1239200

Variable updated

v2 API - 图1240default

Non 2XX error response from server.

put/api/v2/variables/{variableID}v2 API - 图1241

/api/v2/variables/{variableID}

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "labels": [ - { - "name": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "arguments": { - "type": "query", - "values": { - "language": "string", - "query": "string" } }, - "createdAt": "2019-08-24T14:15:22Z", - "description": "string", - "id": "string", - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "labels": "[http://example.com](http://example.com)", - "org": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" }, - "name": "string", - "orgID": "string", - "selected": [ - "string" ], - "updatedAt": "2019-08-24T14:15:22Z" }

List all labels for a variable

Authorizations:

TokenAuthentication

path Parameters
variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

v2 API - 图1242200

A list of all labels for a variable

v2 API - 图1243default

Unexpected error

get/api/v2/variables/{variableID}/labelsv2 API - 图1244

/api/v2/variables/{variableID}/labels

Response samples

  • 200
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "labels": [ - { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } } ], - "links": { - "next": "[http://example.com](http://example.com)", - "prev": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" } }

Add a label to a variable

Authorizations:

TokenAuthentication

path Parameters
variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json

Label to add

labelID
required
string

A label ID. Specifies the label to attach.

Responses

v2 API - 图1245201

The newly added label

v2 API - 图1246default

Unexpected error

post/api/v2/variables/{variableID}/labelsv2 API - 图1247

/api/v2/variables/{variableID}/labels

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "labelID": "string" }

Response samples

  • 201
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "label": { - "id": "string", - "name": "string", - "orgID": "string", - "properties": { - "color": "ffb3b3", - "description": "this is a description" } }, - "links": { - "next": "[http://example.com](http://example.com)", - "prev": "[http://example.com](http://example.com)", - "self": "[http://example.com](http://example.com)" } }

Delete a label from a variable

Authorizations:

TokenAuthentication

path Parameters
labelID
required
string

The label ID to delete.

variableID
required
string

The variable ID.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Responses

204

Delete has been accepted

v2 API - 图1248404

Variable not found

v2 API - 图1249default

Unexpected error

delete/api/v2/variables/{variableID}/labels/{labelID}v2 API - 图1250

/api/v2/variables/{variableID}/labels/{labelID}

Response samples

  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "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

v2 API - 图1251200

A dashboard cells view

v2 API - 图1252404

Cell or dashboard not found

v2 API - 图1253default

Unexpected error

get/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图1254

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "string" }, - "name": "string", - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" }, - "y": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" } }, - "colors": [ - { - "hex": "strings", - "id": "string", - "name": "string", - "type": "min", - "value": 0 } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - "string" ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 } }

Update the view for a cell

Authorizations:

TokenAuthentication

path Parameters
cellID
required
string

The ID of the cell to update.

dashboardID
required
string

The ID of the dashboard to update.

header Parameters
Zap-Trace-Span
string
Example: baggage,[object Object],span_id,1,trace_id,1

OpenTracing span context

Request Body schema: application/json
name
required
string
required
LinePlusSingleStatProperties (object) or XYViewProperties (object) or SingleStatViewProperties (object) or HistogramViewProperties (object) or GaugeViewProperties (object) or TableViewProperties (object) or SimpleTableViewProperties (object) or MarkdownViewProperties (object) or CheckViewProperties (object) or ScatterViewProperties (object) or HeatmapViewProperties (object) or MosaicViewProperties (object) or BandViewProperties (object) or GeoViewProperties (object) (ViewProperties)

Responses

v2 API - 图1256200

Updated cell view

v2 API - 图1257404

Cell or dashboard not found

v2 API - 图1258default

Unexpected error

patch/api/v2/dashboards/{dashboardID}/cells/{cellID}/viewv2 API - 图1259

/api/v2/dashboards/{dashboardID}/cells/{cellID}/view

Request samples

  • Payload

Content type

application/json

Copy

Expand all Collapse all

{ - "name": "string", - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" }, - "y": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" } }, - "colors": [ - { - "hex": "strings", - "id": "string", - "name": "string", - "type": "min", - "value": 0 } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - "string" ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 } }

Response samples

  • 200
  • 404
  • default

Content type

application/json

Copy

Expand all Collapse all

{ - "id": "string", - "links": { - "self": "string" }, - "name": "string", - "properties": { - "adaptiveZoomHide": true, - "axes": { - "x": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" }, - "y": { - "base": "", - "bounds": [ - "string" ], - "label": "string", - "prefix": "string", - "scale": "log", - "suffix": "string" } }, - "colors": [ - { - "hex": "strings", - "id": "string", - "name": "string", - "type": "min", - "value": 0 } ], - "decimalPlaces": { - "digits": 0, - "isEnforced": true }, - "generateXAxisTicks": [ - "string" ], - "generateYAxisTicks": [ - "string" ], - "hoverDimension": "auto", - "legendColorizeRows": true, - "legendHide": true, - "legendOpacity": 0, - "legendOrientationThreshold": 0, - "note": "string", - "position": "overlaid", - "prefix": "string", - "queries": [ - { - "builderConfig": { - "aggregateWindow": { - "fillValues": true, - "period": "string" }, - "buckets": [ - "string" ], - "functions": [ - { - "name": "string" } ], - "tags": [ - { - "aggregateFunctionType": "filter", - "key": "string", - "values": [ - "string" ] } ] }, - "editMode": "builder", - "name": "string", - "text": "string" } ], - "shadeBelow": true, - "shape": "chronograf-v2", - "showNoteWhenEmpty": true, - "staticLegend": { - "colorizeRows": true, - "heightRatio": 0, - "opacity": 0, - "orientationThreshold": 0, - "show": true, - "valueAxis": "string", - "widthRatio": 0 }, - "suffix": "string", - "timeFormat": "string", - "type": "line-plus-single-stat", - "xColumn": "string", - "xTickStart": 0, - "xTickStep": 0, - "xTotalTicks": 0, - "yColumn": "string", - "yTickStart": 0, - "yTickStep": 0, - "yTotalTicks": 0 } }

Write

Write time series data to buckets.

Write data

Writes data to a bucket.

Use this endpoint to send data in line protocol format to InfluxDB.

InfluxDB Cloud

  • Does the following when you send a write request:

    1. Validates the request and queues the write.
    2. If queued, responds with success (HTTP 2xx status code); error otherwise.
    3. Handles the delete asynchronously and reaches eventual consistency.

    To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

    Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

  • Validates the request and handles the write synchronously.
  • If all points were written successfully, responds with HTTP 2xx status code; otherwise, returns the first line that failed.

Required permissions

  • write-buckets or write-bucket BUCKET_ID.

    BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Authorizations:

TokenAuthentication

query Parameters
bucket
required
string

A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket.

org
required
string

An organization name or ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
orgID
string

An organization ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
precision
string (WritePrecision)
Enum: “ms” “s” “us” “ns”

The precision for unix timestamps in the line protocol batch.

header Parameters
Accept
string
Default: application/json
Value: “application/json”

The content type that the client can understand. Writes only return a response body if they fail—for example, due to a formatting problem or quota limit.

InfluxDB Cloud

  • Returns only application/json for format and limit errors.
  • Returns only text/html for some quota limit errors.

InfluxDB OSS

  • Returns only application/json for format and limit errors.

Related guides

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

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the write asynchronously - the write might not have completed yet.

InfluxDB OSS

  • Successfully wrote all points in the batch.

v2 API - 图1260400

Bad request. The response body contains detail about the error.

InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected.

InfluxDB Cloud

  • Returns this error for bucket schema conflicts.

InfluxDB OSS

  • Returns this error if the org parameter or orgID parameter doesn’t match an organization.

v2 API - 图1261401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to this organization and bucket.

v2 API - 图1262404

Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)—for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.

v2 API - 图1263413

The request payload is too large. InfluxDB rejected the batch and did not write any data.

InfluxDB Cloud:

  • Returns this error if the payload exceeds the 50MB size limit.
  • Returns Content-Type: text/html for this error.

InfluxDB OSS:

  • Returns this error only if the Go (golang) ioutil.ReadAll() function raises an error.
  • Returns Content-Type: application/json for this error.

v2 API - 图1264429

Too many requests.

InfluxDB Cloud

  • Returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit.

  • For rate limits that reset automatically, returns a Retry-After header that describes when to try the write again.

  • For limits that can’t reset (for example, cardinality limit), doesn’t return a Retry-After header.

    Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.

InfluxDB OSS

  • Doesn’t return this error.

v2 API - 图1265500

Internal server error. The server encountered an unexpected situation.

v2 API - 图1266503

Service unavailable.

  • Returns this error if the server is temporarily unavailable to accept writes.
  • Returns a Retry-After header that describes when to try the write again.

v2 API - 图1267default

Non 2XX error response from server.

post/api/v2/writev2 API - 图1268

/api/v2/write

Request samples

  • Payload

Content type

text/plain

Copy

  1. airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
  2. airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000

Response samples

  • 400
  • 401
  • 404
  • 413
  • 500
  • default

Content type

application/json

Example

(Cloud) field type conflict thrown by an explicit bucket schema

v2 API - 图1269

(Cloud) field type conflict thrown by an explicit bucket schema

(OSS) organization not found

Copy

Expand all Collapse all

{ - "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" }