Skip to main content
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

RunsThreads
StateNone — each run is isolatedPersistent across runs via values
Lifecyclepending → running → terminalidle → busy → idle (repeats)
ConcurrencyUnlimited parallel runsOne run at a time per thread
HistoryIndividual run recordsCheckpoints after each run
SetupNone — just create a runCreate 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.

​
Further reading