# runstate

> Coordination infrastructure for agent swarms: shared work, rate limits, budgets and completion decisions across every agent, process and machine. A hosted service with TypeScript and Python SDKs over one HTTP API. The hosted preview is PAUSED while the service is rebuilt: the API at api.getrunstate.com does not answer and sign-up is closed. Join the waitlist at https://getrunstate.com/request-access to hear when it reopens.

runstate does not run your agents, call your models, or proxy your traffic. Your agents keep running wherever they already run. You wrap the functions where they would collide (shared work, rate-limited tools, scarce resources, spend) and call them as before. See [/llms-full.txt](https://getrunstate.com/llms-full.txt) for the fuller reference (exact SDK snippets, every building block, errors, limits).

## What runstate is

- [Homepage](https://getrunstate.com/): the full pitch, feature walkthroughs and a code example.
- [Contact](https://getrunstate.com/contact): email hello@getrunstate.com.
- [Join the waitlist](https://getrunstate.com/request-access): the preview is paused; we write when it reopens.
- [Pricing](https://getrunstate.com/pricing): Free, Builder $20/month, Team $99/month, Scale $499/month, Enterprise custom. Metered on operations, never per agent.
- [Request a paid plan](https://getrunstate.com/upgrade): paid plans are free until the preview ends.
- [Documentation](https://docs.getrunstate.com/): guides, the TypeScript and Python SDK reference, the HTTP API reference, errors and limits.

## Quickstart

Install (SDK 0.3.0):

```bash
npm install runstate-sdk
```

```bash
pip install runstate-sdk
```

Set `RUNSTATE_API_KEY` and `RUNSTATE_SPACE_ID` from the console. The SDKs connect to `https://api.getrunstate.com` by default. `RUNSTATE_RUN` (default `default`) names the run every process joins.

TypeScript: wrap a function once, call it as before:

```ts
import runstate from 'runstate-sdk';

const research = runstate.once(researchCompany); // once per run for the same arguments
const search = runstate.limit('search-api', searchWeb, { max: 60, per: 'minute' });
const browse = runstate.slots('browser', openPage, { max: 5 });
const ask = runstate.budget('model-usd', callModel, { reserve: 0.40, cost: (r) => r.usd, limit: 50 });

await research('acme'); // looks like a normal call
await runstate.stop(); // every worker stops taking new work
```

In TypeScript every wrapped function returns a promise, so callers `await` it. Name inline functions passed to `once`, or pass `{ name }`.

Python: the same names as decorators:

```python
import runstate

@runstate.once
def research_company(name: str) -> dict: ...

@runstate.limit("search-api", max=60, per="minute")
async def search_web(query: str) -> list: ...

research_company("acme")
runstate.stop()  # await runstate.astop()
```

Full quickstart (once, a queue, a worker and a producer): [docs quickstart](https://docs.getrunstate.com/quickstart/).

## Core concepts, in the order most teams reach for them

- **once**: work done once per run for the same arguments; every caller, in any process, gets the same result; if the process doing it dies, another caller takes over.
- **limit** and **slots**: a shared rate quota (N units per window) and a cap on how many things run at once, shared by every worker, with fair waiting on the server instead of retry storms.
- **budget**: reserve spend before an expensive call, charge the real cost after, release the rest; the function isn't called if the budget can't cover the reservation.
- **queue**, **gather** and **stop**: hand work to worker processes (`runstate.serve()`), stop when enough results are accepted, and stop a whole run from one call. `runstate.queue(name)` without a handler is producer-only, for workers in another process or language. `job.result({ timeout })` waits for a submitted job.
- **setup**: create or check limits, slots and budgets up front without calling anything (`runstate.setup({ limits, slots, budgets })`).
- **sleep** and **together**: durable timers and "wait until N workers arrive".
- **events** and **status**: the run's event stream and a snapshot of who holds what; the console shows the same.

## SDK and API reference

- TypeScript SDK: `runstate-sdk` on npm (Node ≥ 22). Default export `runstate` with `once`, `limit`, `take`, `slots`, `budget`, `queue`, `serve`, `setup`, `sleep`, `together`, `run`, `child`, `runId`, `stop`, `finish`, `context`, `events`, `status`, `configure`; also the `Runstate` class and `isRunstateError`. [Reference](https://docs.getrunstate.com/sdk/typescript/).
- Python SDK: `runstate-sdk` on PyPI (imports as `runstate`, Python ≥ 3.10). The same names as decorators and module functions; every module function has an `a`-prefixed async form (`astop`, `aserve`, `atake`, `asetup`). `runstate.queue("review")` on its own is producer-only: call it with `review(doc)`, or `await review.acall(doc)` in async code. [Reference](https://docs.getrunstate.com/sdk/python/).
- HTTP API for other languages: [https://api.getrunstate.com/openapi.yaml](https://api.getrunstate.com/openapi.yaml) and the [API reference](https://docs.getrunstate.com/api/). Everything except `/public/v1` needs `Authorization: Bearer <RUNSTATE_API_KEY>`.

## Errors and retries

Every SDK error is a `RunstateError` (`code`, `status`, `requestId`, `retryAfter`, `retryable`). Classes: `ConfigError`, `AuthError`, `StoppedError`, `TimeoutError`, `OnceFailedError`, `TaskFailedError`, `BudgetExceededError`, `ResultTooLargeError`, `ConflictError`, `LeaseLostError`, `UnavailableError`. Busy resources, rate limits and plan concurrency limits are retried inside the SDK, honouring `Retry-After`. Full table: [/llms-full.txt](https://getrunstate.com/llms-full.txt#errors).

## Limits and plans

Free plan: 100,000 operations/month (hard stop), 10 agents working at once, 2 spaces, 7-day data retention, 64 KB per input or result. Plans: Free ($0), Builder ($20/month), Team ($99/month), Scale ($499/month) and Enterprise (custom). Paid plans are requested at https://getrunstate.com/upgrade and are free until the preview ends. Full table: [/llms-full.txt](https://getrunstate.com/llms-full.txt#limits).

## More

- [/llms-full.txt](https://getrunstate.com/llms-full.txt): the fuller reference: every building block, exact SDK snippets, errors and limits, and what runstate never claims.
- [/index.md](https://getrunstate.com/index.md): this homepage's content as plain markdown.
- [/sitemap.xml](https://getrunstate.com/sitemap.xml), [/robots.txt](https://getrunstate.com/robots.txt)