Run Agent - Runtools.ai

curl -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Run the tests and summarize failures.",
    "stream": false,
    "config": {
      "maxTurns": 12
    }
  }'

const result = await rt.agent.run(
  'code-assistant',
  'Run the tests and summarize failures.',
  {
    maxTurns: 12,
  },
);

console.log(result.result);

const first = await rt.agent.run('code-assistant', 'Inspect this repo.', {
  thread: true,
});

await rt.agent.run('code-assistant', 'Now fix the failing test.', {
  threadId: first.threadId,
});

{
  "data": {
    "runId": "run_abc123",
    "sandboxId": "sandbox-abc123",
    "executionMode": "in_sandbox",
    "status": "completed",
    "result": "The test suite is green.",
    "usage": {
      "inputTokens": 1480,
      "outputTokens": 322
    },
    "iterations": 4,
    "threadId": "thr_abc123"
  }
}

{
  "error": {
    "code": "THREAD_BUSY",
    "message": "Thread is busy"
  }
}

POST

run

curl -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Run the tests and summarize failures.",
    "stream": false,
    "config": {
      "maxTurns": 12
    }
  }'

const result = await rt.agent.run(
  'code-assistant',
  'Run the tests and summarize failures.',
  {
    maxTurns: 12,
  },
);

console.log(result.result);

const first = await rt.agent.run('code-assistant', 'Inspect this repo.', {
  thread: true,
});

await rt.agent.run('code-assistant', 'Now fix the failing test.', {
  threadId: first.threadId,
});

{
  "data": {
    "runId": "run_abc123",
    "sandboxId": "sandbox-abc123",
    "executionMode": "in_sandbox",
    "status": "completed",
    "result": "The test suite is green.",
    "usage": {
      "inputTokens": 1480,
      "outputTokens": 322
    },
    "iterations": 4,
    "threadId": "thr_abc123"
  }
}

{
  "error": {
    "code": "THREAD_BUSY",
    "message": "Thread is busy"
  }
}

POST /v1/run is the canonical agent run endpoint. Set stream: false for JSON responses. When stream is omitted or true, the endpoint returns Server-Sent Events for sandbox-backed and managed agents. Runs can target in_sandbox, managed, or local-mac agents. in_sandbox runs wake the linked sandbox when possible. local-mac runs either register a thread for the local sidecar caller or dispatch over RunMesh to the bound device.

Request Body

string

required

Agent slug or ID.

string

User prompt. Either prompt or messages is required.

array

Caller-managed conversation history. Use this when you do not want server-managed thread history.

string

Persist the run into a server-managed thread. Reuse the same ID to continue the thread.

boolean

default:"true"

false returns JSON. true returns Server-Sent Events.

object

Per-run overrides: maxTokens, maxTurns, and temperature.

object

Caller metadata stored with the run.

Response

string

Run ID.

string

Run status, such as completed, registered, or dispatched.

string

Final assistant response for non-streaming runs.

string

Thread ID when threading is active.

string

Active rollout ID when the run is registered for a cloud thread.

string

in_sandbox, managed, or local-mac.

object

Token usage when available.

curl -X POST https://api.runtools.ai/v1/run \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "code-assistant",
    "prompt": "Run the tests and summarize failures.",
    "stream": false,
    "config": {
      "maxTurns": 12
    }
  }'

const result = await rt.agent.run(
  'code-assistant',
  'Run the tests and summarize failures.',
  {
    maxTurns: 12,
  },
);

console.log(result.result);

const first = await rt.agent.run('code-assistant', 'Inspect this repo.', {
  thread: true,
});

await rt.agent.run('code-assistant', 'Now fix the failing test.', {
  threadId: first.threadId,
});

{
  "data": {
    "runId": "run_abc123",
    "sandboxId": "sandbox-abc123",
    "executionMode": "in_sandbox",
    "status": "completed",
    "result": "The test suite is green.",
    "usage": {
      "inputTokens": 1480,
      "outputTokens": 322
    },
    "iterations": 4,
    "threadId": "thr_abc123"
  }
}

{
  "error": {
    "code": "THREAD_BUSY",
    "message": "Thread is busy"
  }
}

Thread APIs

Thread history and live updates are exposed through /v1/threads, not the run endpoint:

curl "https://api.runtools.ai/v1/threads?limit=25" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

const { threads } = await rt.threads.list();
const detail = await rt.threads.get(threads[0].id);
await rt.threads.archive(threads[0].id);

Use /v1/threads/{threadId}/events for durable event history and wss://api.runtools.ai/v1/threads/{threadId}/events?api_key=... for live frames.

Legacy Per-Agent Endpoint

POST /v1/agents/{slug}/run still exists, but new code should prefer POST /v1/run because it has the same request shape used by the SDK and thread helpers.

Deployments Stream Runs & Threads

​Request Body

​Response

​Thread APIs

​Legacy Per-Agent Endpoint

Request Body

Response

Thread APIs

Legacy Per-Agent Endpoint