Tasks | InfluxDB Cloud (TSM) Documentation

GET /api/v2/tasks

List all tasks

Retrieves a list of tasks.

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

Parameters

Query parameters

name string

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

after string

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

user string

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

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

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

Allowed values: active , inactive

limit integer

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.

Default: 100

offset integer

The number of records to skip.

sortBy string

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

Allowed values: name

type string

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

Allowed values: basic , system

scriptID string

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

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the list of tasks.

links string

tasks object[]

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

POST /api/v2/tasks

Create a task

Creates a task and returns the task.

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

InfluxDB Cloud

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

flux: a string of “raw” Flux that contains task options and the script–for example:

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

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

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

Limitations:

You can’t use flux and scriptID for the same task.

Parameters

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body required

The task to create

Content-Type: application/json

cron string

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

description string

The description of the task.

every string

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

flux string

The Flux script that the task runs.

Limitations

If you use the flux property, you can’t use the scriptID and scriptParameters properties.

name string

The name of the task

offset string <duration>

A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.

org string

The name of the organization that owns the task.

orgID string

The ID of the organization that owns the task.

scriptID string

The ID of the script that the task runs.

Limitations

If you use the scriptID property, you can’t use the flux property.

scriptParameters object

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

Limitations

scriptParameters requires scriptID.
If you use the scriptID and scriptParameters properties, you can’t use the flux property.

status string

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "cron": "CRON",
  "description": "DESCRIPTION",
  "every": "EVERY",
  "flux": "FLUX",
  "name": "NAME",
  "offset": "OFFSET",
  "org": "ORG",
  "orgID": "ORGID",
  "scriptID": "SCRIPTID",
  "scriptParameters": {},
  "status": "active"
}'

Responses

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

authorizationID string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt string <date-time>

cron string

A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.

description string

A description of the task.

every string <duration>

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

flux string <flux>

The Flux script that the task executes.

Limitations

If you use the flux property, you can’t use the scriptID and scriptParameters properties.

id required string

labels string

lastRunError string

lastRunStatus string

Allowed: failed , success , canceled

latestCompleted string <date-time>

A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.

links object

Example:

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

labels string

logs string

members string

owners string

runs string

self string

name required string

The name of the task.

offset string <duration>

A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.

org string

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

orgID required string

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

ownerID string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

scriptID string

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

Limitations

If you use the scriptID property, you can’t use the flux property.

Create a task that references a script

scriptParameters object

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

Limitations

To use scriptParameters, you must provide a scriptID.
If you use the scriptID and scriptParameters properties, you can’t use the flux property.

status string

updatedAt string <date-time>

400

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

InfluxDB Cloud

Returns this error if the task doesn’t contain one of flux or scriptID.
Returns this error if the task contains flux and scriptID.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}

Retrieve a task

Retrieves a task.

Parameters

Path parameters

taskID required string

A task ID. Specifies the task to retrieve.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the task.

authorizationID string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt string <date-time>

cron string

A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.

description string

A description of the task.

every string <duration>

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

flux string <flux>

The Flux script that the task executes.

Limitations

If you use the flux property, you can’t use the scriptID and scriptParameters properties.

id required string

labels string

lastRunError string

lastRunStatus string

Allowed: failed , success , canceled

latestCompleted string <date-time>

A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.

links object

Example:

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

labels string

logs string

members string

owners string

runs string

self string

name required string

The name of the task.

offset string <duration>

A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.

org string

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

orgID required string

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

ownerID string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

scriptID string

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

Limitations

If you use the scriptID property, you can’t use the flux property.

Create a task that references a script

scriptParameters object

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

Limitations

To use scriptParameters, you must provide a scriptID.
If you use the scriptID and scriptParameters properties, you can’t use the flux property.

status string

updatedAt string <date-time>

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

PATCH /api/v2/tasks/{taskID}

Update a task

Updates a task, and then cancels all scheduled runs of the task.

Use this endpoint to set, modify, or clear task properties–for example: cron, name, flux, status. Once InfluxDB applies the update, it cancels all previously scheduled runs of the task.

To update a task, pass an object that contains the updated key-value pairs. To activate or inactivate a task, set the status property. "status": "inactive" cancels scheduled runs and prevents manual runs of the task.

InfluxDB Cloud

Use either flux or scriptID to provide the task script.

flux: a string of “raw” Flux that contains task options and the script–for example:

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

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

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

Limitations:

You can’t use flux and scriptID for the same task.

Parameters

Path parameters

taskID required string

A task ID. Specifies the task to update.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body required

An task update to apply.

Content-Type: application/json

cron string

Update the ‘cron’ option in the flux script.

description string

Update the description of the task.

every string

Update the ’every’ option in the flux script.

flux string

Update the Flux script that the task runs.

name string

Update the ’name’ option in the flux script.

offset string

Update the ‘offset’ option in the flux script.

scriptID string

Update the ‘scriptID’ of the task.

scriptParameters object

Update the ‘scriptParameters’ of the task.

status string

Example request Ask AI about this

curl --request PATCH \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "cron": "CRON",
  "description": "DESCRIPTION",
  "every": "EVERY",
  "flux": "FLUX",
  "name": "NAME",
  "offset": "OFFSET",
  "scriptID": "SCRIPTID",
  "scriptParameters": {},
  "status": "active"
}'

Responses

200 Success. The response body contains the updated task.

authorizationID string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt string <date-time>

cron string

A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.

description string

A description of the task.

every string <duration>

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

flux string <flux>

The Flux script that the task executes.

Limitations

If you use the flux property, you can’t use the scriptID and scriptParameters properties.

id required string

labels string

lastRunError string

lastRunStatus string

Allowed: failed , success , canceled

latestCompleted string <date-time>

A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.

links object

Example:

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

labels string

logs string

members string

owners string

runs string

self string

name required string

The name of the task.

offset string <duration>

A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.

org string

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

orgID required string

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

ownerID string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

scriptID string

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

Limitations

If you use the scriptID property, you can’t use the flux property.

Create a task that references a script

scriptParameters object

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

Limitations

To use scriptParameters, you must provide a scriptID.
If you use the scriptID and scriptParameters properties, you can’t use the flux property.

status string

updatedAt string <date-time>

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE /api/v2/tasks/{taskID}

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.

Parameters

Path parameters

taskID required string

A task ID. Specifies the task to delete.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The task and task runs are deleted. Scheduled runs are canceled.

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}/labels

List labels for a task

Retrieves a list of all labels for a task.

Labels may be used for grouping and filtering tasks.

Parameters

Path parameters

taskID required string

The ID of the task to retrieve labels for.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

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

labels string

links string

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

POST /api/v2/tasks/{taskID}/labels

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.

Parameters

Path parameters

taskID required string

The ID of the task to label.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body required

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

Content-Type: application/json

labelID required string

A label ID. Specifies the label to attach.

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "labelID": "LABELID"
}'

Responses

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

label string

links string

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE /api/v2/tasks/{taskID}/labels/{labelID}

Delete a label from a task

Deletes a label from a task.

Parameters

Path parameters

taskID required string

The ID of the task to delete the label from.

labelID required string

The ID of the label to delete.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/labels/{labelID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The label is deleted.

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}/logs

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.

Parameters

Path parameters

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/logs" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

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

events object[]

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}/members

List all task members

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.

Parameters

Path parameters

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/members" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains a list of users that have the member role for a task.

links object

self string <uri>

users object[]

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

POST /api/v2/tasks/{taskID}/members

Add a member to a task

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.

Parameters

Path parameters

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body required

A user to add as a member of the task.

Content-Type: application/json

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.

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/members" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME"
}'

Responses

201 Created. The user is added to task members.

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE /api/v2/tasks/{taskID}/members/{userID}

Remove a member from a task

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Removes a member from a task.

Parameters

Path parameters

userID required string

The ID of the member to remove.

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/members/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Member removed

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}/owners

List all owners of a task

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.

Parameters

Path parameters

taskID required string

The ID of the task to retrieve owners for.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/owners" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200

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.

links object

self string <uri>

users object[]

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

422

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.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

POST /api/v2/tasks/{taskID}/owners

Add an owner for a task

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.

Parameters

Path parameters

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body required

A user to add as an owner of the task.

Content-Type: application/json

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.

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/owners" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME"
}'

Responses

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

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

422

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.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE /api/v2/tasks/{taskID}/owners/{userID}

Remove an owner from a task

Deprecated: Tasks don’t use owner and member roles. Use /api/v2/authorizations to assign user permissions.

Parameters

Path parameters

userID required string

The ID of the owner to remove.

taskID required string

The task ID.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/owners/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Owner removed

default Unexpected error

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

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.

Parameters

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.

limit integer

Limits the number of task runs returned. Default is 100.

Default: 100

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.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the list of task runs.

links string

runs object[]

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

Start a task run, overriding the schedule

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

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

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

Parameters

Path parameters

taskID required string

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body

Content-Type: application/json

scheduledFor string <date-time>

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

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "scheduledFor": "SCHEDULEDFOR"
}'

Responses

201 Success. The run is scheduled to start.

finishedAt string <date-time>

The time (RFC3339Nano date/time format) the run finished executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

flux string

Flux used for the task

id string

links object

Example: {"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}

retry string <uri>

self string <uri>

task string <uri>

log object[]

An array of logs associated with the run.

requestedAt string <date-time>

The time (RFC3339Nano date/time format) the run was manually requested.

Example: "2006-01-02T15:04:05.999999999Z07:00"

scheduledFor string <date-time>

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

startedAt string <date-time>

The time (RFC3339Nano date/time format) the run started executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

status string

Allowed: scheduled , started , failed , success , canceled

taskID string

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

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.

Parameters

Path parameters

taskID required string

The ID of the task to retrieve runs for.

runID required string

The ID of the run to retrieve.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs/{runID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the task run.

finishedAt string <date-time>

The time (RFC3339Nano date/time format) the run finished executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

flux string

Flux used for the task

id string

links object

Example: {"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}

retry string <uri>

self string <uri>

task string <uri>

log object[]

An array of logs associated with the run.

requestedAt string <date-time>

The time (RFC3339Nano date/time format) the run was manually requested.

Example: "2006-01-02T15:04:05.999999999Z07:00"

scheduledFor string <date-time>

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

startedAt string <date-time>

The time (RFC3339Nano date/time format) the run started executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

status string

Allowed: scheduled , started , failed , success , canceled

taskID string

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

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.

Parameters

Path parameters

taskID required string

The ID of the task to cancel.

runID required string

The ID of the task run to cancel.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs/{runID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

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.

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

405

Method not allowed.

InfluxDB Cloud

Always returns this error; doesn’t support cancelling tasks.

InfluxDB OSS v2

Doesn’t return this error.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

GET /api/v2/tasks/{taskID}/runs/{runID}/logs

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.

Parameters

Path parameters

taskID required string

The ID of the task to get logs for.

runID required string

The ID of the run to get logs for.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Example request Ask AI about this

curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs/{runID}/logs" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

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

events object[]

400

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

InfluxDB OSS v2

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

POST /api/v2/tasks/{taskID}/runs/{runID}/retry

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

Parameters

Path parameters

taskID required string

A task ID. Specifies the task to retry.

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.

Header parameters

Zap-Trace-Span string

OpenTracing span context

Request body

Content-Type: application/json

Example request Ask AI about this

curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/tasks/{taskID}/runs/{runID}/retry" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json; charset=utf-8"

Responses

200 Success. The response body contains the queued run.

finishedAt string <date-time>

The time (RFC3339Nano date/time format) the run finished executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

flux string

Flux used for the task

id string

links object

Example: {"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}

retry string <uri>

self string <uri>

task string <uri>

log object[]

An array of logs associated with the run.

requestedAt string <date-time>

The time (RFC3339Nano date/time format) the run was manually requested.

Example: "2006-01-02T15:04:05.999999999Z07:00"

scheduledFor string <date-time>

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

startedAt string <date-time>

The time (RFC3339Nano date/time format) the run started executing.

Example: "2006-01-02T15:04:05.999999999Z07:00"

status string

Allowed: scheduled , started , failed , success , canceled

taskID string

400

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

InfluxDB may return this error for the following reasons:

The task has status: inactive.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

401

Unauthorized. The error may indicate one of the following:

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

code string

The HTTP status code description. Default is unauthorized.

Allowed: unauthorized

message string

A human-readable message that may contain detail about the error.

404

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

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

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

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

default Non 2XX error response from server.

code required string

code is the machine-readable error code.

Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type

err string

Stack of errors that occurred during processing of the request. Useful for debugging.

message string

Human-readable message.

op string

Describes the logical code operation when the error occurred. Useful for debugging.

List all tasks

Parameters

Query parameters

Header parameters

Responses

Create a task

InfluxDB Cloud

Limitations:

Related guides

Parameters

Header parameters

Request body required

Limitations

Limitations

Limitations

Responses

Limitations

Limitations

Related guides

Limitations

InfluxDB Cloud

Retrieve a task

Parameters

Path parameters

Header parameters

Responses

Limitations

Limitations

Related guides

Limitations

InfluxDB OSS v2

Update a task

InfluxDB Cloud

Limitations:

Parameters

Path parameters

Header parameters

Request body required

Responses

Limitations

Limitations

Related guides

Limitations

InfluxDB OSS v2

Delete a task

Parameters

Path parameters

Header parameters

Responses

InfluxDB OSS v2

List labels for a task

Parameters

Path parameters

Header parameters

Responses

InfluxDB OSS v2

Add a label to a task

Parameters

Path parameters

Header parameters

Request body required

Responses

InfluxDB OSS v2

Delete a label from a task

Parameters

Path parameters

Header parameters

Responses

InfluxDB OSS v2

Retrieve all logs for a task

Parameters

Path parameters

Header parameters

Responses

InfluxDB OSS v2

List all task members

Parameters

Path parameters

Header parameters

Responses