> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs vs. threads

> When to use stateless runs and when to use stateful 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.

```bash theme={null}
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](/guides/streaming) 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.

```bash theme={null}
# 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.

## Further reading

* [Threads guide](/guides/threads) for thread state, checkpoints, metadata, and lifecycle details
* [Building a chatbot](/guides/chatbot) for a full walkthrough using threads with CrewAI Flows
* [Runs API reference](/api-reference/runs/create)
* [Threads API reference](/api-reference/threads/create)