8 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

LuauExecutionSessionTask — openapi

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.

Properties

Related Schemas

• LuauExecutionSessionTask_Error

• LuauExecutionSessionTask_Output

Complete Schema

{
  "type": "object",
  "properties": {
    "path": {
      "example": "universes/123/places/123/luau-execution-session-tasks/123e4567-e89b-12d3-a456-426655440000",
      "type": "string",
      "description": "The resource path of the luau execution session task.\n\nFormats:\n* `universes/{universe_id}/places/{place_id}/luau-execution-session-tasks/{luau_execution_session_task_id}`\n* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-session-tasks/{luau_execution_session_task_id}`\n* `universes/{universe_id}/places/{place_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}`\n* `universes/{universe_id}/places/{place_id}/versions/{place_version_id}/luau-execution-sessions/{luau_execution_session_id}/tasks/{luau_execution_session_task_id}`"
    },
    "createTime": {
      "readOnly": true,
      "example": "2023-07-05T12:34:56Z",
      "type": "string",
      "description": "Time when this task was created.",
      "format": "date-time"
    },
    "updateTime": {
      "readOnly": true,
      "example": "2023-07-05T12:34:56Z",
      "type": "string",
      "description": "Time when this task's state last changed.",
      "format": "date-time"
    },
    "user": {
      "readOnly": true,
      "type": "string",
      "description": "The user that created the API key that was used to create this task."
    },
    "state": {
      "readOnly": true,
      "example": "STATE_UNSPECIFIED",
      "enum": [
        "STATE_UNSPECIFIED",
        "QUEUED",
        "PROCESSING",
        "CANCELLED",
        "COMPLETE",
        "FAILED"
      ],
      "type": "string",
      "description": "The task's state. See the State enum for information about each possible\nvalue.\n\nPossible values:\n\n  | Value | Description |\n  | --- | --- |\n  | STATE_UNSPECIFIED | UNSPECIFIED |\n  | QUEUED | The Task is waiting to be processed. |\n  | PROCESSING | The Task has been picked up for processing. |\n  | CANCELLED | The Task has been stopped by the user. |\n  | COMPLETE | The Task has finished processing. The output field contains the output. |\n  | FAILED | The Task failed. The error field contains details about the error. |",
      "format": "enum"
    },
    "script": {
      "type": "string",
      "description": "The script to be run as part of this task.\n\nFor example:\n\n```luau\nlocal x = 3\nlocal y = 4\nreturn x + y\n```",
      "x-immutable": true
    },
    "timeout": {
      "example": "3s",
      "type": "string",
      "description": "Limit for how long the script can run.\n\nThe task fails if the script does not complete within the\nspecified duration.\n\nDefaults to 5 minutes.",
      "format": "duration",
      "x-immutable": true
    },
    "error": {
      "$ref": "#/components/schemas/LuauExecutionSessionTask_Error",
      "description": "Present when the task execution fails. Contains details about the error\nthat caused the failure."
    },
    "output": {
      "$ref": "#/components/schemas/LuauExecutionSessionTask_Output",
      "description": "Present when the task execution succeeds. Contains the output of the\nexecution."
    },
    "binaryInput": {
      "type": "string",
      "description": "Resource path of the binary input to this task. See the documentation for\nthe\n`LuauExecutionSessionTaskBinaryInput` resource for usage details."
    },
    "enableBinaryOutput": {
      "example": true,
      "type": "boolean",
      "description": "If set to true, allows the task to output a large binary object in addition\nto standard return values.\n\nIf `enable_binary_output` is set to true, the task script must return a\n`LuauExecutionTaskOutput` (or equivalent table) and no other return values.\n\nBelow is example code for doing so:\n\n```luau\nlocal buf: buffer = buffer.create(10)\nlocal result: LuauExecutionTaskOutput = {\n  BinaryOutput = buf,\n  ReturnValues = { \"hello world\", 123 }\n}\nreturn result\n```\n\nThe `BinaryOutput` buffer must be no larger than 256 MiB in size.\n\nThe `ReturnValues` array, if given, will be serialized to JSON and made\navailable in the `output` field of the `LuauExecutionSessionTask` resource,\nsimilar to regular return values when not using `enable_binary_output`.\n\nThe binary output can be fetched from the URI in the `binaryOutputUri`\nfield after the task completes. The `binaryOutputUri` is valid for 15\nminutes after task completion.",
      "x-immutable": true
    },
    "binaryOutputUri": {
      "readOnly": true,
      "type": "string",
      "description": "URI for the binary output of this task. See the `enableBinaryOutput` field\nfor usage details."
    }
  },
  "description": "A `LuauExecutionSessionTask` (\"task\" for short) executes a given Luau script\nin the context of a specific version of a place.\n\nIn a task, physics simulation does not run. Server and local scripts within\nthe place also do not automatically run.\n\nThe script may access and update the data model of the place, including\ninvoking any module scripts. However, data model changes are local to the\ntask and cannot be persisted.\n\nThe script can also invoke engine APIs that read and/or modify data stored in\nthe cloud, such as those for DataStores. Exercise caution when using these\nAPIs.\n\nScripts can be up to 4 MB in size and run for up to 5 minutes. Scripts that\nrun for longer than the time limit terminate with an error.\n\nScripts are executed as-is and do not need to be wrapped in a function.\n\nScripts can return values (using the Luau `return` keyword). Return values\nare serialized to JSON and can be retrieved with the `Get\nLuauExecutionSessionTask` API after the task completes. The total size of the\nreturn values after JSON serialization must not exceed 4 MB. If the limit is\nexceeded, the task terminates with an error.\n\nIf the script raises an unhandled error, the task terminates. The error\ninformation can be retrieved with the `GetLuauExecutionSessionTask` API.\n\nStandard output (generated by the Luau `print` function) can be retrieved\nwith the `ListLuauExecutionSessionTaskLogs` method after the task completes.\nA maximum of 450 KB of logs are retained. If the amount of logs exceeds the\nlimit, older logs are discarded.\n\nInformation about a task is retained for 24 hours after task completion.\n\nAt most ten incomplete tasks are allowed per place. Attempting to create more\ntasks while the first ten are incomplete results in a HTTP 429 response.",
  "x-aep-resource": {
    "patterns": [
      "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}"
    ],
    "plural": "luau-execution-session-tasks",
    "singular": "luau-execution-session-task"
  },
  "x-resource": true,
  "x-oneOf": {
    "result": [
      "error",
      "output"
    ]
  }
}