Skip to main content
A run is a single execution of an agent with a specific prompt. You create a run, execute it, and then retrieve the results.

​
Run lifecycle

  queued ──→ running ──→ completed
                    └──→ failed
    │
    └──→ cancelled
StatusDescription
queuedCreated, waiting for exec
runningExecuting in a sandbox
completedFinished successfully
failedExecution error
cancelledCancelled by user

​
Step 1: Create a run

Endpoint
POST /agent/v1/run
Creating a run queues it — it does not start execution. This lets you register watchers before the agent starts working. 
const run = await client.agents.runs.create({
  agentId: 'agent_abc123',
  prompt:
    'Search vault vault_xyz for all references to force majeure clauses and compile a summary.',
})

console.log(run.id) // run_xxx
console.log(run.status) // "queued"

​
Run parameters

ParameterTypeRequiredDescription
agentIdstringyesAgent to run
promptstringyesTask for the agent
guidancestringnoAdditional context or constraints for this specific run
modelstringnoOverride the agent’s default model

​
Guidance vs. instructions

The agent’s instructions define its general behavior. The run’s guidance adds context for a specific execution: 
// Agent instructions: "You analyze contracts for risk."
// Run guidance adds specifics for this particular run:
const run = await client.agents.runs.create({
  agentId: agent.id,
  prompt: 'Analyze the master services agreement in vault vault_abc',
  guidance:
    'Focus on indemnification and limitation of liability. The client is in healthcare, so flag any HIPAA-related concerns.',
})

​
Model override

Use a different model for a specific run without changing the agent: 
const run = await client.agents.runs.create({
  agentId: agent.id,
  prompt: 'Quick summary of document vault_abc/obj_xyz',
  model: 'anthropic/claude-haiku-3.5', // faster, cheaper for simple tasks
})

​
Step 2: Execute the run

Endpoint
POST /agent/v1/run/:id/exec
Execution starts a durable workflow that spins up a sandbox and runs the agent. The endpoint returns immediately — the work happens in the background. 
const result = await client.agents.runs.exec(run.id)
console.log(result.status) // "running"
Response
{
  "id": "run_abc123",
  "status": "running",
  "workflowId": "wrun_xxx",
  "message": "Run started. Poll /run/:id/status or register a watcher."
}
Exec is a one-shot operation. Calling exec on a run that’s already been started returns 409 Conflict. Each run can only be executed once.

​
Step 3: Wait for completion

Two options: poll the status endpoint, or register a watcher before executing.

​
Option A: Poll

let status = await client.agents.runs.getStatus(run.id)

while (status.status === 'running') {
  await new Promise((r) => setTimeout(r, 2000))
  status = await client.agents.runs.getStatus(run.id)
}

if (status.status === 'completed') {
  const details = await client.agents.runs.getDetails(run.id)
  console.log(details.result.output)
}

​
Option B: Watch (webhook callback)

Register a callback URL before executing. You’ll receive a POST when the run completes: 
// 1. Create run
const run = await client.agents.runs.create({
  agentId: agent.id,
  prompt: 'Analyze the contract...',
})

// 2. Register watcher BEFORE exec
await client.agents.runs.watch(run.id, {
  callbackUrl: 'https://your-app.com/webhooks/agent-complete',
})

// 3. Execute
await client.agents.runs.exec(run.id)
// Your webhook receives the result when done
See Monitoring & Analysis for details on webhook payloads and polling patterns.

​
Cancel a run

Endpoint
POST /agent/v1/run/:id/cancel
Cancel a queued or running run. Cancelling a completed run returns the current status without error. 
const result = await client.agents.runs.cancel(run.id)
console.log(result.status) // "cancelled"

​
Complete example

Create an agent, run a complex multi-step task, and get the results: 
import Casedev from '@case.dev/sdk'

const client = new Casedev({ apiKey: process.env.CASEDEV_API_KEY })

// Create a research agent
const agent = await client.agents.create({
  name: 'Legal Researcher',
  instructions: `You are a legal research assistant. When given a topic:
1. Search vaults for relevant documents
2. Use legal search to find related case law and statutes
3. Compile a research memo in markdown
4. Upload the memo to the vault
5. Return the vault object ID and download URL`,
})

// Run it
const run = await client.agents.runs.create({
  agentId: agent.id,
  prompt:
    'Research employment discrimination laws relevant to the documents in vault vault_abc. Upload a report.',
})

await client.agents.runs.exec(run.id)

// Wait for completion
let status = await client.agents.runs.getStatus(run.id)
while (status.status === 'running') {
  console.log(`Running... ${Math.round(status.durationMs / 1000)}s`)
  await new Promise((r) => setTimeout(r, 5000))
  status = await client.agents.runs.getStatus(run.id)
}

// Get results
const details = await client.agents.runs.getDetails(run.id)
console.log(details.result.output)

​
Typical run times

Task complexityExampleDuration
Simple”Say hello”10-20s
Medium”List services and describe them”20-45s
Complex”Search vault, research laws, compile report, upload”2-6 min
Most of the run time is the AI thinking and making API calls — sandbox startup is under 10 seconds.

​
Next: Monitor and analyze

Learn how to get detailed results, audit trails, and set up webhooks →