--- 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: 24162 product: InfluxDB Cloud (TSM) version: cloud --- [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 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](/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 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](#) ```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 201 Success. The response body contains the script and its metadata. `createdAt` string `description` string `id` string `language` string `name` required string `orgID` required string `script` required string The script to execute. `updatedAt` string `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](/influxdb/cloud/api-guide/api-invokable-scripts/). #### Related Guides - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### Parameters ##### Path parameters `scriptID` required string 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 200 Success. The response body contains the script. `createdAt` string `description` string `id` string `language` string `name` required string `orgID` required string `script` required string The script to execute. `updatedAt` string `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. #### Related Guides - [Invoke custom scripts](/influxdb/cloud/api-guide/api-invokable-scripts/) #### 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](#) ```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 200 Success. The response body contains the updated script. `createdAt` string `description` string `id` string `language` string `name` required string `orgID` required string `script` required string The script to execute. `updatedAt` string `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](/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` required string 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 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 : ```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` 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](#) ```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 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 : ```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` required string 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 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.