Invokable Scripts

Download InfluxDB Cloud (TSM) API Spec
Store, manage, and execute custom Flux scripts in InfluxDB Cloud. Scripts accept runtime parameters and can be invoked via dedicated endpoints.
GET /api/v2/scripts

List scripts

Lists scripts.

Parameters

Query parameters
offset integer

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

For more information about pagination parameters, see Pagination.

limit integer
The maximum number of scripts to return. Default is 100.
Default: 100
name string
The script name. Lists scripts with the specified name.
Example request Ask AI about this
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the list of scripts.
scripts object[]
400 Bad request. InfluxDB is unable to parse the request. The response body contains detail about the 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.
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.
POST /api/v2/scripts

Create a script

Creates an invokable script and returns the script.

Request body required

The script to create.
Content-Type: application/json
description required string
Script description. A description of the script.
language required string
name required string
Script name. The name must be unique within the organization.
script required string
The script to execute.
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "language": "flux",
  "name": "NAME",
  "script": "SCRIPT"
}'

Responses

201 Success. The response body contains the script and its metadata.
createdAt string <date-time>
description string
id string
language string
name required string
orgID required string
script required string
The script to execute.
updatedAt string <date-time>
url string
The invocation endpoint address.
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.
422 Unprocessable entity.
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.
GET /api/v2/scripts/{scriptID}

Retrieve a script

Retrieves a script.

Parameters

Path parameters
scriptID required string
A script ID. Retrieves the specified script.
Example request Ask AI about this
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the script.
createdAt string <date-time>
description string
id string
language string
name required string
orgID required string
script required string
The script to execute.
updatedAt string <date-time>
url string
The invocation endpoint address.
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.
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/scripts/{scriptID}

Update a script

Updates an invokable script.

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

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

Limitations

  • If you send an empty request body, the script will neither update nor store an empty script, but InfluxDB will respond with an HTTP 200 status code.

Parameters

Path parameters
scriptID required string
A script ID. Updates the specified script.

Request body required

An object that contains the updated script properties to apply.
Content-Type: application/json
description string
A description of the script.
script string
The script to execute.
Example request Ask AI about this
curl --request PATCH \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "script": "SCRIPT"
}'

Responses

200 Success. The response body contains the updated script.
createdAt string <date-time>
description string
id string
language string
name required string
orgID required string
script required string
The script to execute.
updatedAt string <date-time>
url string
The invocation endpoint address.
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.
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/scripts/{scriptID}

Delete a script

Deletes a script and all associated records.

Limitations

  • You can delete only one script per request.
  • If the script ID you provide doesn’t exist for the organization, InfluxDB responds with an HTTP 204 status code.

Parameters

Path parameters
scriptID required string
A script ID. Deletes the specified script.
Example request Ask AI about this
curl --request DELETE \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 Success. The script is queued for deletion.
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/scripts/{scriptID}/invoke

Invoke a script

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

The following sample script contains a mybucket parameter :

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

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

{
  "params": {
    "mybucket": "air_sensor"
  }
}

Parameters

Path parameters
scriptID required string
A script ID. Runs the specified script.

Request body

Content-Type: application/json
params object
The script parameters. params contains key-value pairs that map values to the params.keys in a script. When you invoke a script with params, InfluxDB passes the values as invocation parameters to the script.
Example request Ask AI about this
curl --request POST \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/invoke" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "params": {}
}'

Responses

200 Success. The response body contains the result of the script execution.
400 Bad request. InfluxDB is unable to parse the request. The response body contains detail about the 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.
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.
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.
GET /api/v2/scripts/{scriptID}/params

Find script parameters.

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

The following sample script contains a mybucket parameter :

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

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

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

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

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

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

Parameters

Path parameters
scriptID required string
A script ID. The script to analyze for params.
Example request Ask AI about this
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/params" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the parameters found, along with their types.
params object
The params keys and value type defined in the script.
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.
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.

Was this page helpful?

Thank you for your feedback!