Threads API

Threads represent conversation contexts for multi-turn agent interactions. Each thread maintains full conversation history and supports real-time streaming responses via Server-Sent Events (SSE).

The Thread Object


{
  "id": "thread_nM2Ew9gtEpg2lSlZMFu48",
  "userId": "user_abc123",
  "environmentId": "env_kJDvlIZ0mXZI0JrqbHj25",
  "agentId": "agent_xyz789",
  "title": "Build REST API",
  "status": "completed",
  "messageCount": 5,
  "inputTokens": 2500,
  "outputTokens": 1200,
  "totalCost": 0.037,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T14:22:00.000Z",
  "metadata": {}
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier (`thread_*`)
`userId`	string	Owner user ID
`environmentId`	string	Associated environment
`agentId`	string	Agent used for execution
`title`	string	Thread title
`status`	string	`active`, `running`, `completed`, `failed`, `cancelled`
`messageCount`	number	Total messages
`inputTokens`	number	Total input tokens used
`outputTokens`	number	Total output tokens used
`totalCost`	number	Total cost in USD
`appId`	string	Associated application ID
`metadata`	object	Custom key-value metadata
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Create Thread (Unified API)

Create a thread with intelligent behavior inference. The API determines what to do based on what you provide.


POST /v1/threads

Request Body

Parameter	Type	Required	Description
`environmentId`	string	No	Target environment (uses default if not specified)
`agentId`	string	No	Agent to use
`title`	string	No	Thread title
`messages`	array	No	Initial messages to execute
`task`	string	No	Task description (alias for first message)
`stream`	boolean	No	Enable SSE streaming (default: true when messages provided)
`schedule`	object	No	Schedule configuration
`attachments`	array	No	File attachments
`appId`	string	No	Application identifier
`metadata`	object	No	Custom metadata

Execution configuration (mcpServers, envVars, secrets) should be set on the Environment, not per-request. Agent configuration (model, instructions) should be set on the Agent.

Behavior Inference

The API automatically determines behavior based on your request:

messages	schedule	Behavior
No	No	Create empty thread (JSON)
Yes	No	Execute immediately (SSE stream)
Yes	Yes	Create thread + schedule (JSON)
No	Yes	Error - nothing to schedule

Example: Immediate Execution (Streaming)

cURL


curl -X POST https://api.computer-agents.com/v1/threads \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Create a hello.py file" }],
    "stream": true
  }'

Response (SSE Stream):


data: {"type":"thread.created","thread":{"id":"thread_xxx",...}}
data: {"type":"response.created","response":{...}}
data: {"type":"response.output_item.added","item":{"type":"message",...}}
data: {"type":"response.item.completed","item":{...}}
data: {"type":"response.completed","response":{...}}
data: {"type":"stream.completed"}

Example: Non-Streaming Execution


curl -X POST https://api.computer-agents.com/v1/threads \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Create hello.py" }],
    "stream": false
  }'

Response:


{
  "thread": {
    "id": "thread_xxx",
    "status": "completed",
    ...
  },
  "execution": {
    "success": true,
    "response": "I've created hello.py with a simple greeting.",
    "actions": ["Created: hello.py"],
    "durationMs": 5234,
    "usage": {
      "inputTokens": 150,
      "outputTokens": 50
    }
  }
}

Example: Create Empty Thread


curl -X POST https://api.computer-agents.com/v1/threads \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_xyz789",
    "title": "My Project"
  }'

Response:


{
  "thread": {
    "id": "thread_xxx",
    "environmentId": "env_xyz789",
    "title": "My Project",
    "status": "active",
    "messageCount": 0
  }
}

Example: Create Scheduled Thread


curl -X POST https://api.computer-agents.com/v1/threads \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Run daily cleanup" }],
    "schedule": {
      "type": "recurring",
      "name": "Daily Cleanup",
      "cronExpression": "0 9 * * *",
      "timezone": "America/New_York"
    }
  }'

Response:


{
  "thread": { ... },
  "schedule": {
    "id": "sched_xxx",
    "name": "Daily Cleanup",
    "scheduleType": "recurring",
    "cronExpression": "0 9 * * *",
    "enabled": true
  }
}

List Threads


GET /v1/threads

Query Parameters

Parameter	Type	Default	Description
`environmentId`	string	-	Filter by environment
`agentId`	string	-	Filter by agent
`appId`	string	-	Filter by app
`status`	string	-	Filter: `active`, `running`, `completed`, `failed`, `cancelled`
`limit`	number	50	Max results (1-100)
`offset`	number	0	Pagination offset

Example


curl "https://api.computer-agents.com/v1/threads?status=completed&limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "id": "thread_nM2Ew9gtEpg2lSlZMFu48",
      "title": "Build REST API",
      "status": "completed",
      "messageCount": 5,
      "totalCost": 0.037,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "has_more": true,
  "total_count": 42
}

Get Thread


GET /v1/threads/:threadId

Example


curl https://api.computer-agents.com/v1/threads/thread_xxx \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "thread": {
    "id": "thread_nM2Ew9gtEpg2lSlZMFu48",
    "userId": "user_abc123",
    "environmentId": "env_kJDvlIZ0mXZI0JrqbHj25",
    "title": "Build REST API",
    "status": "completed",
    "messageCount": 5,
    "inputTokens": 2500,
    "outputTokens": 1200,
    "totalCost": 0.037,
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Update Thread


PATCH /v1/threads/:threadId

Request Body

Parameter	Type	Description
`title`	string	New title
`metadata`	object	Updated metadata

Example


curl -X PATCH https://api.computer-agents.com/v1/threads/thread_xxx \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

Delete Thread


DELETE /v1/threads/:threadId

Permanently deletes a thread and all its messages.

Example


curl -X DELETE https://api.computer-agents.com/v1/threads/thread_xxx \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "success": true
}

Send Follow-up Message

Continue a conversation in an existing thread. The agent receives full conversation context.


POST /v1/threads/:threadId/messages

Request Body

Parameter	Type	Required	Description
`content`	string	Yes	Message content
`attachments`	array	No	File attachments

Example

cURL


curl -X POST https://api.computer-agents.com/v1/threads/thread_xxx/messages \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Now add error handling"}'

Response (SSE Stream)


data: {"type":"response.created","response":{...}}
data: {"type":"response.output_item.added","item":{...}}
data: {"type":"response.item.completed","item":{...}}
data: {"type":"response.completed","response":{...}}
data: {"type":"stream.completed"}

Get Thread Messages


GET /v1/threads/:threadId/messages

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Max results
`offset`	number	0	Pagination offset
`order`	string	`asc`	Sort order: `asc` or `desc`

Example


curl "https://api.computer-agents.com/v1/threads/thread_xxx/messages?order=desc&limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "id": "msg_xxx",
      "threadId": "thread_xxx",
      "role": "user",
      "content": "Create hello.py",
      "createdAt": "2025-01-15T10:00:00Z"
    },
    {
      "id": "msg_yyy",
      "role": "assistant",
      "content": "I've created hello.py with the following content...",
      "durationMs": 5000,
      "inputTokens": 500,
      "outputTokens": 250,
      "createdAt": "2025-01-15T10:00:05Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}

Get Thread Logs

Get execution logs for a thread.


GET /v1/threads/:threadId/logs

Response


{
  "logs": [
    {
      "time": "10:00:00",
      "message": "Starting task...",
      "type": "info",
      "eventType": "agent_message"
    },
    {
      "time": "10:00:02",
      "message": "Creating file: hello.py",
      "type": "info",
      "eventType": "tool_call"
    }
  ],
  "threadId": "thread_xxx",
  "status": "completed",
  "duration": "45",
  "totalCost": 0.037,
  "inputTokens": 2500,
  "outputTokens": 1200
}

Get Thread Diffs

Get file changes made by the agent.


GET /v1/threads/:threadId/diffs

Response


{
  "diffs": [
    {
      "path": "hello.py",
      "type": "create",
      "content": "print('Hello, World!')"
    },
    {
      "path": "README.md",
      "type": "modify",
      "additions": 5,
      "deletions": 2
    }
  ]
}

Cancel Thread Execution

Cancel an in-progress execution.


POST /v1/threads/:threadId/cancel

Example


curl -X POST https://api.computer-agents.com/v1/threads/thread_xxx/cancel \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "success": true,
  "threadId": "thread_xxx",
  "message": "Execution cancelled successfully"
}

Errors

Status	Error	Description
400	`Bad Request`	Invalid parameters
402	`Payment Required`	Insufficient budget
404	`Not Found`	Thread not found
409	`Conflict`	Thread already processing

Budget Error


{
  "error": "Payment Required",
  "message": "Insufficient budget to execute",
  "budgetStatus": {
    "balance": 0.50,
    "estimatedCost": 2.00
  }
}

Streaming (SSE) - Handle real-time events
Schedules - Automate recurring tasks
Environments - Configure execution context
Agents - Customize agent behavior

Threads API

The Thread Object

Attributes

Create Thread (Unified API)

Request Body

Behavior Inference

Example: Immediate Execution (Streaming)

cURL

JavaScript

Example: Non-Streaming Execution

Example: Create Empty Thread

Example: Create Scheduled Thread

List Threads

Query Parameters

Example

Response

Get Thread

Example

Response

Update Thread

Request Body

Example

Delete Thread

Example

Response

Send Follow-up Message

Request Body

Example

cURL

JavaScript

Response (SSE Stream)

Get Thread Messages

Query Parameters

Example

Response

Get Thread Logs

Response

Get Thread Diffs

Response

Cancel Thread Execution

Example

Response

Errors

Budget Error

Related