---
title: Invokable Scripts
description: Store, manage, and execute custom Flux scripts in InfluxDB Cloud. Scripts accept runtime parameters and can be invoked via dedicated endpoints.
url: https://docs.influxdata.com/influxdb/cloud/api/invokable-scripts/
estimated_tokens: 6327
product: InfluxDB Cloud (TSM)
version: cloud
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/cloud/api/invokable-scripts/
---

[Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml)

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](/influxdb/cloud/api-guide/api-invokable-scripts/).

#### Related guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Query parameters

`offset`integer

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

For more information about pagination parameters, see [Pagination](/influxdb/cloud/api/#tag/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](#)

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

#### Responses

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

`scripts`object[]

400Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the error.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultUnexpected error.

`code`requiredstring

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](/resources/videos/api-invokable-scripts/)and returns the script.

#### Related guides

* [Invokable scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)
* [Creating custom InfluxDB endpoints](/resources/videos/api-invokable-scripts/)

#### Request bodyrequired

The script to create.

Content-Type:`application/json`

`description`requiredstring

Script description. A description of the script.

`language`requiredstring

`name`requiredstring

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

`script`requiredstring

The script to execute.

Example request[Ask AI about this](#)

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

201Success.
The response body contains the script and its metadata.

`createdAt`string \<date-time\>

`description`string

`id`string

`language`string

`name`requiredstring

`orgID`requiredstring

`script`requiredstring

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

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.

422Unprocessable entity.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultUnexpected error.

`code`requiredstring

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](/influxdb/cloud/api-guide/api-invokable-scripts/).

#### Related Guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Path parameters

`scriptID`requiredstring

A script ID.
Retrieves the specified script.

Example request[Ask AI about this](#)

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

#### Responses

200Success. The response body contains the script.

`createdAt`string \<date-time\>

`description`string

`id`string

`language`string

`name`requiredstring

`orgID`requiredstring

`script`requiredstring

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.

404Not found.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultNon 2XX error response from server.

`code`requiredstring

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.

#### Related Guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Path parameters

`scriptID`requiredstring

A script ID.
Updates the specified script.

#### Request bodyrequired

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](#)

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

200Success. The response body contains the updated script.

`createdAt`string \<date-time\>

`description`string

`id`string

`language`string

`name`requiredstring

`orgID`requiredstring

`script`requiredstring

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.

404Not found.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultNon 2XX error response from server.

`code`requiredstring

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](/influxdb/cloud/api-guide/api-invokable-scripts/) 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.

#### Related Guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Path parameters

`scriptID`requiredstring

A script ID.
Deletes the specified script.

Example request[Ask AI about this](#)

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

#### Responses

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

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

`code`requiredstring

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.

defaultNon 2XX error response from server.

`code`requiredstring

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 :

```json
"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:

```json
{
  "params": {
    "mybucket": "air_sensor"
  }
}
```

#### Related guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Path parameters

`scriptID`requiredstring

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](#)

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

200Success.
The response body contains the result of the script execution.

400Bad request.
InfluxDB is unable to parse the request.
The response body contains detail about the error.

`code`requiredstring

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.

404Not found.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultUnexpected error.

`code`requiredstring

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 :

```json
"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:

```json
{
  "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.

#### Related guides

* [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/)

#### Parameters

##### Path parameters

`scriptID`requiredstring

A script ID.
The script to analyze for params.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/scripts/{scriptID}/params" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

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

404Not found.

`code`requiredstring

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.

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

`code`requiredstring

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.

defaultUnexpected error.

`code`requiredstring

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.