LuauExecutionSessionTask

A LuauExecutionSessionTask ("task" for short) executes a given Luau script in the context of a specific version of a place.

In a task, physics simulation does not run. Server and local scripts within the place also do not automatically run.

The script may access and update the data model of the place, including invoking any module scripts. However, data model changes are local to the task and cannot be persisted.

The script can also invoke engine APIs that read and/or modify data stored in the cloud, such as those for DataStores. Exercise caution when using these APIs.

Scripts can be up to 4 MB in size and run for up to 5 minutes. Scripts that run for longer than the time limit terminate with an error.

Scripts are executed as-is and do not need to be wrapped in a function.

Scripts can return values (using the Luau return keyword). Return values are serialized to JSON and can be retrieved with the Get LuauExecutionSessionTask API after the task completes. The total size of the return values after JSON serialization must not exceed 4 MB. If the limit is exceeded, the task terminates with an error.

If the script raises an unhandled error, the task terminates. The error information can be retrieved with the GetLuauExecutionSessionTask API.

Standard output (generated by the Luau print function) can be retrieved with the ListLuauExecutionSessionTaskLogs method after the task completes. A maximum of 450 KB of logs are retained. If the amount of logs exceeds the limit, older logs are discarded.

Information about a task is retained for 24 hours after task completion.

At most ten incomplete tasks are allowed per place. Attempting to create more tasks while the first ten are incomplete results in a HTTP 429 response.

  • RESOURCE PATHS
  • /cloud/v2/universes/{universe_id}/places/{place_id}/luau-execution-session-tasks
  • /cloud/v2/universes/{universe_id}/places/{place_id}/versions/{version_id}/luau-execution-session-tasks
  • /cloud/v2/universes/{universe_id}/places/{place_id}/luau-execution-sessions/{luau_execution_session_id}/tasks
  • /cloud/v2/universes/{universe_id}/places/{place_id}/versions/{version_id}/luau-execution-sessions/{luau_execution_session_id}/tasks

Attributes

pathstring

The resource path of the luau execution session task.

Formats:

  • universes/{universe_id}/places/{place_id}/luau-execution-session-tasks/{luau_execution_session_task_id}
  • universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-session-tasks/{luau_execution_session_task_id}
  • universes/{universe_id}/places/{place_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}
  • universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}.
createTimestring
Output Only

Time when this task was created. This string is formatted as a Timestamp.

updateTimestring
Output Only

Time when this task's state last changed. This string is formatted as a Timestamp.

userstring
Output Only

The user that created the API key that was used to create this task.

stateEnum<string>
Output Only

The task's state. See the State enum for information about each possible value.

Possible values:

ValueDescription
STATE_UNSPECIFIEDUNSPECIFIED
QUEUEDThe Task is waiting to be processed.
PROCESSINGThe Task has been picked up for processing.
CANCELLEDThe Task has been stopped by the user.
COMPLETEThe Task has finished processing. The output field contains the output.
FAILEDThe Task failed. The error field contains details about the error.
scriptstring
Immutable

The script to be run as part of this task.

For example:

local x = 3

local y = 4

return x + y

```.
timeoutstring
Immutable

Limit for how long the script can run.

The task fails if the script does not complete within the specified duration.

Defaults to 5 minutes.

One of the following for result:

errorobject

Present when the task execution fails. Contains details about the error that caused the failure.

outputobject

Present when the task execution succeeds. Contains the output of the execution.

Base URL
https://apis.roblox.com
The LuauExecutionSessionTask Resource
{

  "path": "universes/123/places/123/luau-execution-session-tasks/123e4567-e89b-12d3-a456-426655440000",

  "createTime": "2023-07-05T12:34:56Z",

  "updateTime": "2023-07-05T12:34:56Z",

  "user": "string",

  "state": "STATE_UNSPECIFIED",

  "script": "string",

  "timeout": "3s",

  "error": {

    "code": "ERROR_CODE_UNSPECIFIED",

    "message": "string"

  }

}

LuauExecutionSessionTask

Create Luau Execution Session Task
Beta

POST /cloud/v2/universes/{universe_id}/places/{place_id}/luau-execution-session-tasks

Creates a task but does not wait for the task to complete.

To check whether a task has completed, call the GetLuauExecutionSessionTask method and inspect the state field of the returned resource.

Quotas:

  • 5 calls per minute per API key owner
  • 45 calls per minute per IP address
Scopes
universe.place.luau-execution-session:write
RequestPath Parameters
universe_idstring
Required

The universe ID.

place_idstring
Required

The place ID.

Request BodyLuauExecutionSessionTask
ResponseLuauExecutionSessionTask
POST /cloud/v2/universes/{universe_id}/places/{place_id}/luau-execution-session-tasks
curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe_id}/places/{place_id}/luau-execution-session-tasks' \

  -H 'x-api-key: {your-api-key}' \

  -H 'Content-Type: application/json' \

  --data '{

  "script": "string",

  "timeout": "3s"

}'
Response
{

  "path": "universes/123/places/123/luau-execution-session-tasks/123e4567-e89b-12d3-a456-426655440000",

  "createTime": "2023-07-05T12:34:56Z",

  "updateTime": "2023-07-05T12:34:56Z",

  "user": "string",

  "state": "STATE_UNSPECIFIED",

  "script": "string",

  "timeout": "3s",

  "error": {

    "code": "ERROR_CODE_UNSPECIFIED",

    "message": "string"

  }

}