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"

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."
  }'

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."
  }'

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"
  }'

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"]
  }'

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"

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"

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"

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"

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"

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

Get Started

Platform

Resources

Documentation Index

​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