Runs vs. threads

Crewship has two execution modes: runs and threads. Every deployment supports both out of the box.

Runs

A run is a single, stateless execution of your crew. You send input, the crew does its work, you get output. Each run is isolated — it shares nothing with other runs and has no memory of previous executions.

curl -X POST https://api.crewship.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_id": "dep_abc123", "input": {"topic": "AI agents"}}'

A run moves through pending, running, then lands on succeeded, failed, or canceled. You can stream events in real time or poll for the result. Use runs when:

The task is self-contained (write a report, analyze a dataset, process a batch)
The crew doesn’t need context from previous executions
You want to fire off many executions in parallel
The workload is triggered by a webhook, cron, or automated pipeline

Threads

A thread is a persistent conversation context scoped to a deployment. You create a thread once, then run your crew inside it multiple times. Each run receives the thread’s current state, and when it finishes, the state updates. The next run picks up where the last one left off.

# Create a thread
curl -X POST https://api.crewship.dev/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_id": "dep_abc123"}'

# Run inside it
curl -X POST https://api.crewship.dev/v1/threads/thr_xyz789/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Research AI agents in healthcare"}}'

# Follow up — the crew remembers the first message
curl -X POST https://api.crewship.dev/v1/threads/thr_xyz789/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Now focus on diagnostic applications"}}'

Only one run can execute in a thread at a time. If a run is already in progress, new requests return a 409 Conflict. Use threads when:

Users interact with the crew multiple times per session (chatbots, support agents)
The crew’s output depends on conversation history, not just the current input
You need iterative refinement (“generate a plan”, then “make the budget more detailed”)
Multi-step workflows require human review between steps

Quick comparison

	Runs	Threads
State	None — each run is isolated	Persistent across runs via `values`
Lifecycle	`pending` → `running` → terminal	`idle` → `busy` → `idle` (repeats)
Concurrency	Unlimited parallel runs	One run at a time per thread
History	Individual run records	Checkpoints after each run
Setup	None — just create a run	Create thread first, then run inside it

The short version

Does the crew need to remember anything from previous executions? If no, use a run. If yes, use a thread. Trying to fake statefulness by stuffing prior context into run inputs gets messy fast, and you lose checkpoints, history, and the concurrency guarantees that threads provide.

Getting Started

CLI Reference

Configuration

Guides

Runs

Threads

Quick comparison

The short version

Further reading

​Runs

​Threads

​Quick comparison

​The short version

​Further reading

Runs

Threads

Quick comparison

The short version

Further reading