runstate docs

The hosted preview is paused

api.getrunstate.com is not answering and sign-up is closed while the service is rebuilt. These docs describe the SDKs and API as they stood; the packages on npm and PyPI still install, but they have nothing to connect to. Join the waitlist and we will write when it reopens.

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: which work is done and what its result was, how much of a shared rate limit is left, how many slots are free, how much budget is committed, and whether the run should stop. 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. You wrap the functions where agents would otherwise collide, and call them as before.

Start here

QuickstartRun the same function from several processes and watch it run once. Then hand work to a worker. About ten minutes.

ConceptsRuns, once, limits, slots, budgets and queues: 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.

Once and queuesDo work once per run with a shared result, hand work to worker processes, and take over when a worker dies.

Limits and slotsShared rate limits and slots, so agents wait their turn instead of stampeding.

Spend budgetsReserve spend before expensive work, charge the real cost, release the rest.

Gather, stop and waitStop when enough results are good, stop a whole run from one call, and wait durably.

Events and monitoringThe console, the event stream and run status.

LangGraph and OpenAI Agents SDKUse runstate inside LangGraph and the OpenAI Agents SDK.

Reference

TypeScript SDKEvery function and option in runstate-sdk for Node 22 and later.

Python SDKEvery decorator and function, sync and async, for Python 3.10 and later.

HTTP APIEvery endpoint, generated from the OpenAPI document. Use it from any language.

Errors & retriesEvery SDK error class, and what the SDKs retry for you.

What it looks like

Wrap a function once where you define it, then call it as before:

TypeScript

import runstate from 'runstate-sdk'; // reads RUNSTATE_API_KEY and RUNSTATE_SPACE_ID

// Runs once per run for the same arguments. Every caller gets the same result.
const research = runstate.once(researchCompany);

// Every agent draws from one search-API limit and waits its turn.
const search = runstate.limit('search-api', searchWeb, { max: 60, per: 'minute' });

// At most five browsers at once, across every machine.
const browse = runstate.slots('browser', openPage, { max: 5 });

// One spend ceiling for the whole swarm.
const ask = runstate.budget('model-usd', callModel, { reserve: 0.4, cost: (r) => r.usd, limit: 50 });

await research('acme');
await runstate.stop(); // every worker stops taking new work

Python

import runstate  # reads RUNSTATE_API_KEY and RUNSTATE_SPACE_ID


# Runs once per run for the same arguments. Every caller gets the same result.
@runstate.once
def research_company(name: str) -> dict: ...


# Every agent draws from one search-API limit and waits its turn.
@runstate.limit("search-api", max=60, per="minute")
def search_web(query: str) -> list: ...


# At most five browsers at once, across every machine.
@runstate.slots("browser", max=5)
def open_page(url: str) -> str: ...


# One spend ceiling for the whole swarm.
@runstate.budget("model-usd", reserve=0.40, cost=lambda r: r.usd, limit=50)
def call_model(prompt: str): ...


research_company("acme")
runstate.stop()  # every worker stops taking new work

The SDKs cover TypeScript and Python. From any other language, use the HTTP API directly.

Status

The hosted preview is paused while the service is rebuilt. There is nothing to sign up for right now; join the waitlist and we will write when it reopens.

For agents and LLM tools, this site is also available as llms.txt, and every page has a Markdown version (add .md to the path, or use Copy page).