Skip to main content

​
Sessions

A Session (also referred to as a Thread) represents a conversational context with the AI agent. It holds the configuration for the computer environment and the agent’s instructions.

​
Create a session

Creates a new session, storing your instructions and deployment configuration. POST /api/sessions Body 
{ 
  "prompts": {
    "userPrompt": "Go to example.com and extract the pricing table.", // Required
    "goalPrompt": "Save the extracted pricing into a file called pricing.csv", // Required
    "systemPrompt": "You are a helpful data extraction bot." // Optional
  },
  "template": "giga-standard", // Optional: The OS image to use
  "duration": 1, // Optional: Hours to keep the sandbox alive (1-24)
  "deploymentId": "dep_xxx" // Optional: Attach to an existing deployment
}
Response (201) 
{
  "threadId": "uuid",
  "messageId": "uuid",
  "deploymentConfig": {
    "template": "giga-standard",
    "duration": 1,
    "prompts": { ... }
  }
}

​
Get a session

Retrieves the details of an existing session. GET /api/sessions/{threadId} Response (200) 
{ 
  "thread": { 
    // Serialized thread object containing history and metadata
  } 
}

​
Runs

A Run is the actual execution of the AI agent responding to a message within a Session. Starting a run is what actually provisions the computer and begins the automation.

​
Start a run

Triggers the AI agent to execute a task. POST /api/sessions/{threadId}/runs Body 
{ 
  "message": "Start the task now." 
}
Response (201) 
{
  "threadId": "uuid",
  "runId": "run_xxx",
  "publicAccessToken": "token",
  "messageId": "uuid"
}

​
Get a run

Checks the status of an active or completed run. GET /api/sessions/{threadId}/runs/{runId} Response (200) 
{
  "id": "run_xxx",
  "status": "QUEUED|RUNNING|COMPLETED|FAILED|...",
  "isCompleted": false,
  "isErrored": false,
  "metadata": {
    "sandboxId": "optional",
    "vncUrl": "optional",
    "sandboxStatus": "initializing|ready|failed|restored"
  }
}