Skip to main content

​
Overview

Tasks represent code execution requests in Executor. The Tasks API provides functions to create, retrieve, and manage task lifecycle and metadata.

​
Main Functions

​
createTask

Creates a new task for code execution. This is a workspace action that requires authentication.
​
code
string
required
The JavaScript/TypeScript code to execute
​
timeoutMs
number
Task timeout in milliseconds. Defaults to DEFAULT_TASK_TIMEOUT_MS if not specified. Maximum value is MAX_TASK_TIMEOUT_MS.
​
runtimeId
string
The runtime environment to execute the task in. If not specified, a default runtime will be used.
​
metadata
object
Optional metadata to attach to the task for tracking and context
​
accountId
Id<'accounts'>
The account ID associated with this task execution
​
waitForResult
boolean
If true, waits for the task to complete before returning
​
id
string
Unique task identifier
​
code
string
The code that will be executed
​
runtimeId
string
Runtime environment identifier
​
status
TaskStatus
Current task status: "queued", "running", "completed", "failed", "timed_out", or "denied"
​
timeoutMs
number
Task timeout in milliseconds
​
workspaceId
Id<'workspaces'>
Workspace this task belongs to
​
accountId
Id<'accounts'>
Account that created the task
​
clientId
string
Client identifier for tracking
​
createdAt
number
Unix timestamp of task creation
​
updatedAt
number
Unix timestamp of last update
​
startedAt
number
Unix timestamp when task execution started
​
completedAt
number
Unix timestamp when task completed
​
error
string
Error message if task failed
​
exitCode
number
Process exit code for completed tasks
// Example: Create a task with timeout
const task = await createTask({
  code: 'console.log("Hello from Executor")',
  timeoutMs: 30000,
  runtimeId: 'default',
  metadata: { source: 'api-client', version: '1.0' }
});

console.log(`Task created: ${task.id}`);

​
Internal Functions

​
createTask (Internal)

Internal mutation for creating tasks with full control over workspace and account associations.
​
id
string
required
Unique task identifier
​
code
string
required
Code to execute
​
runtimeId
string
required
Runtime identifier
​
timeoutMs
number
Timeout in milliseconds
​
metadata
object
Task metadata
​
workspaceId
Id<'workspaces'>
required
Workspace ID
​
accountId
Id<'accounts'>
Account ID
​
clientId
string
Client identifier

​
getTask

Retrieves a task by its ID.
​
taskId
string
required
The task identifier
Returns the task record or null if not found. 
const task = await getTask({ taskId: 'task_abc123' });
if (task) {
  console.log(`Status: ${task.status}`);
}

​
listTasks

Lists all tasks in a workspace, ordered by creation time (most recent first).
​
workspaceId
Id<'workspaces'>
required
Workspace to list tasks from
Returns up to 500 most recent tasks. 
const tasks = await listTasks({ workspaceId });
console.log(`Found ${tasks.length} tasks`);

​
getTaskInWorkspace

Retrieves a task only if it belongs to the specified workspace.
​
taskId
string
required
Task identifier
​
workspaceId
Id<'workspaces'>
required
Workspace ID to verify against
Returns the task or null if not found or workspace mismatch.

​
listQueuedTaskIds

Retrieves task IDs for tasks in the "queued" status, ordered by creation time.
​
limit
number
Maximum number of task IDs to return (default: 20)
Returns an array of task ID strings. 
const queuedIds = await listQueuedTaskIds({ limit: 50 });
console.log(`${queuedIds.length} tasks waiting in queue`);

​
markTaskRunning

Transitions a task from "queued" to "running" status.
​
taskId
string
required
Task to mark as running
Returns the updated task or null if the task wasn’t in queued status.

​
markTaskFinished

Marks a task as completed with a final status.
​
taskId
string
required
Task identifier
​
status
CompletedTaskStatus
required
Final status: "completed", "failed", "timed_out", or "denied"
​
exitCode
number
Process exit code
​
error
string
Error message if task failed
await markTaskFinished({
  taskId: 'task_abc123',
  status: 'completed',
  exitCode: 0
});

​
setTaskStorageDefaultInstance

Sets the default storage instance for a task at a given scope level.
​
taskId
string
required
Task identifier
​
scopeType
StorageScopeType
required
Storage scope: "scratch", "account", "workspace", or "organization"
​
instanceId
string
required
Storage instance identifier
​
setCurrent
boolean
If true (default), also sets this as the current instance

​
trackTaskStorageAccess

Records storage instance access by a task.
​
taskId
string
required
Task identifier
​
instanceId
string
required
Storage instance that was accessed
​
scopeType
StorageScopeType
Storage scope type
​
accessType
StorageAccessType
required
Type of access: "opened", "provided", or "accessed"
await trackTaskStorageAccess({
  taskId: 'task_abc123',
  instanceId: 'storage_xyz',
  scopeType: 'workspace',
  accessType: 'opened'
});
  • TaskStatus: "queued" | "running" | "completed" | "failed" | "timed_out" | "denied"
  • CompletedTaskStatus: "completed" | "failed" | "timed_out" | "denied"
  • StorageScopeType: "scratch" | "account" | "workspace" | "organization"
  • StorageAccessType: "opened" | "provided" | "accessed"

Build docs developers (and LLMs) love

Get started for freeTalk to us