Execute Runs

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

This page covers the run lifecycle APIs. If you want the simpler one-call execute flow that returns the final answer directly, see Execute.

Run lifecycle

  queued ──→ running ──→ completed
                    └──→ failed
    │
    └──→ cancelled

Status	Description
`queued`	Created, waiting for exec
`running`	Executing in a sandbox
`completed`	Finished successfully
`failed`	Execution error
`cancelled`	Cancelled by user

List runs

Endpoint

GET /agent/v1/run

Retrieve runs for your organization with optional filters and cursor-based pagination.

curl "https://api.case.dev/agent/v1/run?agentId=agent_abc123&status=completed&limit=20" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev agent:v1:run list --agent-id agent_abc123 --status completed --limit 20

const { runs, hasMore, nextCursor } = await client.agent.v1.run.list({
  agentId: 'agent_abc123',
  status: 'completed',
  limit: 20,
})

// Fetch next page
if (hasMore) {
  const page2 = await client.agent.v1.run.list({ cursor: nextCursor })
}

response = client.agent.v1.run.list(
    agent_id="agent_abc123",
    status="completed",
    limit=20,
)

# Fetch next page
if response.has_more:
    page2 = client.agent.v1.run.list(cursor=response.next_cursor)

response, _ := client.Agent.V1.Run.List(ctx, casedev.AgentV1RunListParams{
	AgentID: casedev.F("agent_abc123"),
	Status:  casedev.F("completed"),
	Limit:   casedev.F(int64(20)),
})
fmt.Println(response)

Query parameters

Parameter	Type	Required	Description
`agentId`	string	no	Filter by agent ID
`status`	string	no	Filter by status (`queued`, `running`, `completed`, `failed`, `cancelled`)
`limit`	integer	no	Max results per page (1-250, default 50)
`cursor`	string	no	Run ID from a previous page’s `nextCursor`

Response

{
  "runs": [
    {
      "id": "run_abc123",
      "agentId": "agent_abc123",
      "status": "completed",
      "prompt": "Search vault vault_xyz for all references to...",
      "model": "anthropic/claude-sonnet-4.6",
      "createdAt": "2026-03-01T12:00:00Z",
      "startedAt": "2026-03-01T12:00:01Z",
      "completedAt": "2026-03-01T12:02:30Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "run_abc122"
}

The prompt field is truncated to 200 characters in list responses. Use the details endpoint to get the full prompt.

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.

curl -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "prompt": "Search vault vault_xyz for all references to force majeure clauses and compile a summary."
  }'

casedev agent:v1:run create \
  --agent-id agent_abc123 \
  --prompt "Search vault vault_xyz for all references to force majeure clauses and compile a summary."

const run = await client.agent.v1.run.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 = client.agent.v1.run.create(
    agent_id="agent_abc123",
    prompt="Search vault vault_xyz for all references to force majeure clauses and compile a summary.",
)

print(run.id)      # run_xxx
print(run.status)  # "queued"

run, _ := client.Agent.V1.Run.New(ctx, casedev.AgentV1RunNewParams{
	AgentID: casedev.F("agent_abc123"),
	Prompt:  casedev.F("Search vault vault_xyz for all references to force majeure clauses and compile a summary."),
})
fmt.Printf("Run ID: %s, Status: %s\n", run.ID, run.Status)

Run parameters

Parameter	Type	Required	Description
`agentId`	string	yes	Agent to run
`prompt`	string	yes	Task for the agent
`guidance`	string	no	Additional context or constraints for this specific run
`model`	string	no	Override the agent’s default model
`objectIds`	string[]	no	Scope this run to specific vault object IDs (runtime restriction)

Guidance vs. instructions

The agent’s instructions define its general behavior. The run’s guidance adds context for a specific execution:

curl -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "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."
  }'

casedev agent:v1:run create \
  --agent-id $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."

// Agent instructions: "You analyze contracts for risk."
// Run guidance adds specifics for this particular run:
const run = await client.agent.v1.run.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.',
})

# Agent instructions: "You analyze contracts for risk."
# Run guidance adds specifics for this particular run:
run = client.agent.v1.run.create(
    agent_id=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.",
)

run, _ := client.Agent.V1.Run.New(ctx, casedev.AgentV1RunNewParams{
	AgentID:  casedev.F(agent.ID),
	Prompt:   casedev.F("Analyze the master services agreement in vault vault_abc"),
	Guidance: casedev.F("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:

curl -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "prompt": "Quick summary of document vault_abc/obj_xyz",
    "model": "anthropic/claude-haiku-3.5"
  }'

casedev agent:v1:run create \
  --agent-id $AGENT_ID \
  --prompt "Quick summary of document vault_abc/obj_xyz" \
  --model "anthropic/claude-haiku-3.5"

const run = await client.agent.v1.run.create({
  agentId: agent.id,
  prompt: 'Quick summary of document vault_abc/obj_xyz',
  model: 'anthropic/claude-haiku-3.5', // faster, cheaper for simple tasks
})

run = client.agent.v1.run.create(
    agent_id=agent.id,
    prompt="Quick summary of document vault_abc/obj_xyz",
    model="anthropic/claude-haiku-3.5",  # faster, cheaper for simple tasks
)

run, _ := client.Agent.V1.Run.New(ctx, casedev.AgentV1RunNewParams{
	AgentID: casedev.F(agent.ID),
	Prompt:  casedev.F("Quick summary of document vault_abc/obj_xyz"),
	Model:   casedev.F("anthropic/claude-haiku-3.5"),
})

Object ID scoping

Restrict a run to specific vault objects at runtime. This is useful when you want a general-purpose agent to only work with specific documents for a particular task:

curl -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "prompt": "Summarize these depositions and identify contradictions.",
    "objectIds": ["obj_depo_001", "obj_depo_002", "obj_depo_003"]
  }'

casedev agent:v1:run create \
  --agent-id $AGENT_ID \
  --prompt "Summarize these depositions and identify contradictions." \
  --object-ids obj_depo_001,obj_depo_002,obj_depo_003

const run = await client.agent.v1.run.create({
  agentId: agent.id,
  prompt: 'Summarize these depositions and identify contradictions.',
  objectIds: ['obj_depo_001', 'obj_depo_002', 'obj_depo_003'],
})

run = client.agent.v1.run.create(
    agent_id=agent.id,
    prompt="Summarize these depositions and identify contradictions.",
    object_ids=["obj_depo_001", "obj_depo_002", "obj_depo_003"],
)

response, _ := client.Agent.V1.Run.Create(ctx)
fmt.Println(response)

Object scoping is applied at runtime, not at agent creation. This means the same agent can work with different sets of documents on each run. The agent’s vaultIds restriction (set at creation) is still enforced — objectIds adds a further narrowing within allowed vaults.

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.

curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/exec" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev agent:v1:run exec --id $RUN_ID

const result = await client.agent.v1.run.exec(run.id)
console.log(result.status) // "running"

result = client.agent.v1.run.exec(run.id)
print(result.status)  # "running"

result, _ := client.Agent.V1.Run.Exec(ctx, run.ID)
fmt.Println(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

# Poll until status is "completed"
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/status" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"
# Repeat until status is "completed", then fetch details:
# curl -s "https://api.case.dev/agent/v1/run/$RUN_ID" \
#   -H "Authorization: Bearer $CASEDEV_API_KEY"

# Poll until completed
casedev agent:v1:run get-status --id $RUN_ID
# Repeat until status is "completed", then:
casedev agent:v1:run get-details --id $RUN_ID

let status = await client.agent.v1.run.getStatus(run.id)

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

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

import time

status = client.agent.v1.run.get_status(run.id)

while status.status == "running":
    time.sleep(2)
    status = client.agent.v1.run.get_status(run.id)

if status.status == "completed":
    details = client.agent.v1.run.get_details(run.id)
    print(details.result.output)

status, _ := client.Agent.V1.Run.GetStatus(ctx, run.ID)

for status.Status == "running" {
	time.Sleep(2 * time.Second)
	status, _ = client.Agent.V1.Run.GetStatus(ctx, run.ID)
}

if status.Status == "completed" {
	details, _ := client.Agent.V1.Run.GetDetails(ctx, run.ID)
	fmt.Println(details.Result.Output)
}

Option B: Watch (webhook callback)

# 1. Create run
curl -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_abc123",
    "prompt": "Analyze the contract..."
  }'

# 2. Register watcher BEFORE exec
curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/watch" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callbackUrl": "https://your-app.com/webhooks/agent-complete" }'

# 3. Execute
curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/exec" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# 1. Create run
casedev agent:v1:run create \
  --agent-id $AGENT_ID \
  --prompt "Analyze the contract..."

# 2. Register watcher BEFORE exec
casedev agent:v1:run watch \
  --id $RUN_ID \
  --callback-url "https://your-app.com/webhooks/agent-complete"

# 3. Execute
casedev agent:v1:run exec --id $RUN_ID
# Your webhook receives the result when done

// 1. Create run
const run = await client.agent.v1.run.create({
  agentId: agent.id,
  prompt: 'Analyze the contract...',
})

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

// 3. Execute
await client.agent.v1.run.exec(run.id)
// Your webhook receives the result when done

# 1. Create run
run = client.agent.v1.run.create(
    agent_id=agent.id,
    prompt="Analyze the contract...",
)

# 2. Register watcher BEFORE exec
client.agent.v1.run.watch(
    run.id,
    callback_url="https://your-app.com/webhooks/agent-complete",
)

# 3. Execute
client.agent.v1.run.exec(run.id)
# Your webhook receives the result when done

// 1. Create run
run, _ := client.Agent.V1.Run.New(ctx, casedev.AgentV1RunNewParams{
	AgentID: casedev.F(agent.ID),
	Prompt:  casedev.F("Analyze the contract..."),
})

// 2. Register watcher BEFORE exec
client.Agent.V1.Run.Watch(ctx, run.ID, casedev.AgentV1RunWatchParams{
	CallbackURL: casedev.F("https://your-app.com/webhooks/agent-complete"),
})

// 3. Execute
client.Agent.V1.Run.Exec(ctx, run.ID)
// Your webhook receives the result when done

See Monitoring & Analysis for details on webhook payloads and polling patterns.

Step 4: Stream run events

Endpoint

GET /agent/v1/run/:id/events

The run events endpoint streams SSE for run execution with server-side replay buffering. It includes synthetic terminal events emitted by Case.dev:

run.completed
run.failed
run.cancelled

Use this endpoint to drive live progress UI and to recover from disconnects.

Replay after reconnect

You can replay from a sequence number using either:

Query param: lastEventId
Header: Last-Event-ID

# Stream live (and replay from the beginning)
curl -N "https://api.case.dev/agent/v1/run/$RUN_ID/events?lastEventId=0" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# Replay using the Last-Event-ID header
curl -N "https://api.case.dev/agent/v1/run/$RUN_ID/events" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Last-Event-ID: 42"

Example SSE events

id: 12
event: message.part.updated
data: {"type":"message.part.updated",...}

id: 18
event: run.completed
data: {"type":"run.completed","runId":"run_...","status":"completed",...}

If the run is already terminal when you connect, the endpoint returns buffered events and then sends a close event.

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.

curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/cancel" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

casedev agent:v1:run cancel --id $RUN_ID

const result = await client.agent.v1.run.cancel(run.id)
console.log(result.status) // "cancelled"

result = client.agent.v1.run.cancel(run.id)
print(result.status)  # "cancelled"

result, _ := client.Agent.V1.Run.Cancel(ctx, run.ID)
fmt.Println(result.Status) // "cancelled"

Complete example

Create an agent, run a complex multi-step task, and get the results:

# Create a research agent
AGENT=$(curl -s -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal Researcher",
    "instructions": "You are a legal research assistant. When given a topic: search vaults, find case law, compile a research memo, upload the memo to the vault, and return the vault object ID."
  }')
AGENT_ID=$(echo "$AGENT" | jq -r '.id')

# Create and execute the run
RUN=$(curl -s -X POST https://api.case.dev/agent/v1/run \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"agentId\": \"$AGENT_ID\",
    \"prompt\": \"Research employment discrimination laws relevant to the documents in vault vault_abc. Upload a report.\"
  }")
RUN_ID=$(echo "$RUN" | jq -r '.id')

curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/exec" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# Poll and fetch details
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/status" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

# Create a research agent
casedev agent:v1:agents create \
  --name "Legal Researcher" \
  --instructions "You are a legal research assistant. Search vaults, find case law, compile memos, and upload results."

# Run it
casedev agent:v1:run create \
  --agent-id $AGENT_ID \
  --prompt "Research employment discrimination laws relevant to the documents in vault vault_abc."

casedev agent:v1:run exec --id $RUN_ID

# Poll and get results
casedev agent:v1:run get-status --id $RUN_ID
casedev agent:v1:run get-details --id $RUN_ID

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.agent.v1.run.create({
  agentId: agent.id,
  prompt:
    'Research employment discrimination laws relevant to the documents in vault vault_abc. Upload a report.',
})

await client.agent.v1.run.exec(run.id)

// Wait for completion
let status = await client.agent.v1.run.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.agent.v1.run.getStatus(run.id)
}

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

import time
import casedev

client = casedev.Casedev(api_key="sk_case_xxx")

# Create a research agent
agent = 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
run = client.agent.v1.run.create(
    agent_id=agent.id,
    prompt="Research employment discrimination laws relevant to the documents in vault vault_abc. Upload a report.",
)

client.agent.v1.run.exec(run.id)

# Wait for completion
status = client.agent.v1.run.get_status(run.id)
while status.status == "running":
    print(f"Running... {round(status.duration_ms / 1000)}s")
    time.sleep(5)
    status = client.agent.v1.run.get_status(run.id)

# Get results
details = client.agent.v1.run.get_details(run.id)
print(details.result.output)

// Create a research agent
agent, _ := client.Agents.New(ctx, casedev.AgentNewParams{
	Name:         casedev.F("Legal Researcher"),
	Instructions: casedev.F("You are a legal research assistant. Search vaults, find case law, compile memos, and upload results."),
})

// Run it
run, _ := client.Agent.V1.Run.New(ctx, casedev.AgentV1RunNewParams{
	AgentID: casedev.F(agent.ID),
	Prompt:  casedev.F("Research employment discrimination laws relevant to the documents in vault vault_abc. Upload a report."),
})

client.Agent.V1.Run.Exec(ctx, run.ID)

// Wait for completion
status, _ := client.Agent.V1.Run.GetStatus(ctx, run.ID)
for status.Status == "running" {
	fmt.Printf("Running... %ds\n", status.DurationMs/1000)
	time.Sleep(5 * time.Second)
	status, _ = client.Agent.V1.Run.GetStatus(ctx, run.ID)
}

// Get results
details, _ := client.Agent.V1.Run.GetDetails(ctx, run.ID)
fmt.Println(details.Result.Output)

Typical run times

Task complexity	Example	Duration
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 →

Get Started

Platform

Resources

Run lifecycle

List runs

Query parameters

Response

Step 1: Create a run

Run parameters

Guidance vs. instructions

Model override

Object ID scoping

Step 2: Execute the run

Step 3: Wait for completion

Option A: Poll

Option B: Watch (webhook callback)

Step 4: Stream run events

Replay after reconnect

Cancel a run

Complete example

Typical run times

Next: Monitor and analyze

​Run lifecycle

​List runs

​Query parameters

​Response

​Step 1: Create a run

​Run parameters

​Guidance vs. instructions

​Model override

​Object ID scoping

​Step 2: Execute the run

​Step 3: Wait for completion

​Option A: Poll

​Option B: Watch (webhook callback)

​Step 4: Stream run events

​Replay after reconnect

​Cancel a run

​Complete example

​Typical run times

​Next: Monitor and analyze

Run lifecycle

List runs

Query parameters

Response

Step 1: Create a run

Run parameters

Guidance vs. instructions

Model override

Object ID scoping

Step 2: Execute the run

Step 3: Wait for completion

Option A: Poll

Option B: Watch (webhook callback)

Step 4: Stream run events

Replay after reconnect

Cancel a run

Complete example

Typical run times

Next: Monitor and analyze