# runstate docs

> runstate is the coordination backbone for agent swarms. Your agents keep running where they run; runstate keeps their shared work, rate limits, budgets and results consistent.

Source: https://docs.getrunstate.com/

Once you run more than a handful of agents in parallel, they start stepping on each other: two agents do the same task, fifty agents hit the same API and retry together, the swarm overspends overnight, and work disappears when a worker crashes.

runstate is a hosted service with TypeScript and Python SDKs that holds the state your agents need to agree on: who owns a piece of work, what its result was, how much of a shared quota is left, how much budget is committed, and whether the run is done. It keeps that state correct when individual agents crash, restart or run late.

runstate does not run your agents, call your models or sit in your request path. Your agents, prompts and frameworks stay where they are, and they call runstate at the points where they need to coordinate.

## Start here

- [Quickstart](https://docs.getrunstate.com/quickstart/): Submit a task from one process, finish it in another, and read back its durable result. About ten minutes.
- [Concepts](https://docs.getrunstate.com/concepts/): Runs, work queues, tasks, claims and leases: the handful of ideas every guide builds on.

## Guides

Each guide covers one problem teams hit when they go from one agent to many, in the order most teams run into them.

- [Claims, shared tasks and takeover](https://docs.getrunstate.com/guides/work-once/): Ownership of a key, shared tasks with one recorded result, and takeover when a worker dies.
- [Quotas and concurrency pools](https://docs.getrunstate.com/guides/share-capacity/): Shared quotas, concurrency pools and admission, so agents wait their turn instead of stampeding.
- [Spend budgets](https://docs.getrunstate.com/guides/budgets/): Reserve spend before expensive work, settle the real cost, release the rest.
- [Task groups and cancellation](https://docs.getrunstate.com/guides/completion-and-cancellation/): Decide once when the work is done, and stop handing out new work across the whole run.
- [Events and monitoring](https://docs.getrunstate.com/guides/observability/): The console, the event journal, live watch and diagnostics.
- [LangGraph and OpenAI Agents SDK](https://docs.getrunstate.com/guides/integrations/): Use runstate inside LangGraph and the OpenAI Agents SDK.

## Reference

- [TypeScript SDK](https://docs.getrunstate.com/sdk/typescript/): Every class and method in runstate-sdk for Node 22 and later.
- [Python SDK](https://docs.getrunstate.com/sdk/python/): AsyncRunstate and the blocking Runstate client, with the differences from TypeScript called out.
- [HTTP API](https://docs.getrunstate.com/api/): Every endpoint, generated from the OpenAPI document.
- [Errors & retries](https://docs.getrunstate.com/errors/): Every error code, its HTTP status, and what the SDKs retry for you.

## What it looks like

A few calls inside the agent code you already have:

**TypeScript**

```ts
import { Runstate } from 'runstate-sdk';

const rs = new Runstate(); // reads RUNSTATE_API_KEY, RUNSTATE_SPACE_ID, RUNSTATE_BASE_URL
const run = await rs.scopes.create(); // one run of your swarm

// Only one agent works on Acme at a time. A crashed owner's lease expires.
await run.claim('company:acme').run(async () => {
  await researchCompany('acme');
});

// Every agent draws from one search-API quota and waits its turn.
await run.quota('search-api').take();

// One spend ceiling for the whole swarm.
const spend = await run.budget('research-usd').reserve({ amount: '0.40' });
const cost = await callExpensiveModel();
await spend.settle({ amount: cost.usd, usageKey: cost.requestId });
```

**Python**

```python
from runstate import AsyncRunstate

rs = AsyncRunstate()  # reads RUNSTATE_API_KEY, RUNSTATE_SPACE_ID, RUNSTATE_BASE_URL
run = await rs.scopes.create()  # one run of your swarm

async def research(lease):
    await research_company("acme")

# Only one agent works on Acme at a time. A crashed owner's lease expires.
await run.claim("company:acme").run(research)

# Every agent draws from one search-API quota and waits its turn.
await run.quota("search-api").take()

# One spend ceiling for the whole swarm.
spend = await run.budget("research-usd").reserve(amount="0.40")
cost = await call_expensive_model()
await spend.settle(amount=cost.usd, usage_key=cost.request_id)
```

The quota and budget in this example are created once with `rs.quotas.ensure()` and `rs.budgets.ensure()`; the guides show the full setup.

## Status

runstate is in a private developer preview: free, invite-only, and without an SLA. The hosted service runs in a single EU region. [Request access](https://getrunstate.com/request-access) to get a space and API keys.

For agents and LLM tools, this site is also available as [llms.txt](https://docs.getrunstate.com/llms.txt), and every page has a Markdown version (add `.md` to the path, or use **Copy page**).