/state-stores.md. The full docset is at /llms-full.md and the index is at /llms.md.State stores (beta)
A state store is a small, named key-value store that belongs to your organisation. Use one for the live state an experiment shares while it runs: the best score so far, a counter, a lock, a config value. Every key holds a JSON value and a version number. Conditional writes protect against concurrent updates while the key and store remain in place; deleting and recreating either resets versions and requires separate coordination.
Stores are for coordination, not bulk data. Keep large inputs and outputs in datasets and artifacts, and put a pointer to them in a store if other processes need to find them.
Get access
State stores are in beta. Accounts must be approved before they, or any API key they own, can use them. Ask for access. Until your account is approved, every command returns STATE_ACCESS_REQUIRED:
Error: STATE_ACCESS_REQUIRED — State stores are in beta. Ask C3 for access.
Commands
c3 state create <store> [--json]
c3 state ls [--json]
c3 state show <store> [--json]
c3 state rm <store> [--yes] [--json]
c3 state keys <store> [--prefix P] [--limit N] [--all] [--json]
c3 state get <store> <key> [--json]
c3 state put <store> <key> <value|-> [--string] [--if-version N | --if-absent] [--json]
c3 state del <store> <key> [--if-version N] [--json]
c3 state <subcommand> --help prints the details and examples for each one.
Stores
c3 state create exp-42 # names: 1-64 lowercase letters, digits, . _ or -
c3 state ls # every store in your organisation
c3 state show exp-42 # key count and size against the limits
c3 state rm exp-42 # asks first; --yes for scripts
NAME KEYS SIZE LAST WRITE CREATED BY
exp-42 3 1.2 KB 2026-11-19 14:05 UTC auth0|alice
Everyone approved in your organisation sees the same stores. Deleting a store removes every key in it and cannot be undone; a new store with the same name starts empty.
Keys
c3 state put exp-42 best '{"score": 0.91}' # any JSON value
c3 state put exp-42 status running --string # store plain text
cat config.json | c3 state put exp-42 config - # read the value from stdin
c3 state get exp-42 best # prints only the value
c3 state get exp-42 best --json # value, version, updated_at, updated_by
c3 state keys exp-42 --prefix worker/ --all # list keys
c3 state del exp-42 lock
c3 state get prints the value and nothing else, so it pipes straight into other tools: c3 state get exp-42 best | jq .score. Keys can contain / and are listed in key order.
Conditional writes
A new key starts at version 1; every update increases its version by one. Two flags make a write conditional, and a failed condition writes nothing:
| Flag | Writes only if |
|---|---|
--if-version N | the key is still at version N |
--if-absent | the key does not exist yet |
$ c3 state put exp-42 best '{"score": 0.93}' --if-version 4
Error: STATE_CONFLICT — exp-42/best is at version 5, not 4
Every error exits with status 1 and starts with the error code, so scripts can branch on the code in the message.
Deleting and recreating a key resets its version to 1. Deleting and recreating a store also starts all keys afresh. Versions do not identify a key or store across recreation: if Alice reads score 0.91 at version 1, Bob deletes and recreates it with score 0.99 at version 1, Alice's stale --if-version 1 write of 0.93 succeeds. A stale conditional delete can likewise remove the replacement key.
The lock, best-score and counter examples below require that no other process deletes and recreates the key or store during the operation. Coordinate deletion separately. Version checks alone do not prove lock ownership across recreation; keep lock deletion under the owner's control and prevent store recreation while workers are using it.
A lock
Only one process gets the lock; the others see STATE_CONFLICT and move on.
if c3 state put exp-42 lock "$HOSTNAME" --string --if-absent; then
run_exclusive_step
c3 state del exp-42 lock
fi
Keep the best score
Read the current version, then write only if nobody changed it in between. On a conflict, read again and retry.
while :; do
current=$(c3 state get exp-42 best --json)
version=$(jq .version <<<"$current")
best=$(jq .value.score <<<"$current")
awk "BEGIN { exit !($score > $best) }" || break # not better: done
c3 state put exp-42 best "{\"score\": $score}" --if-version "$version" && break
done
A counter
while :; do
current=$(c3 state get exp-42 done --json)
next=$(( $(jq .value <<<"$current") + 1 ))
c3 state put exp-42 done "$next" --if-version "$(jq .version <<<"$current")" && break
done
Start the counter once with c3 state put exp-42 done 0 --if-absent.
Using a store from a job
Jobs do not receive C3 credentials, so a script running on C3 can only reach a store with an API key you supply. Create a dedicated key with c3 apikey create, give it to the job only for as long as you need it, and revoke it afterwards with c3 apikey revoke. Be aware that anything you put in the project folder is uploaded with the workspace and kept in C3 storage, and that a key printed by your script ends up in its logs. Built-in credentials for jobs are planned.
Dashboard and coding agents
The State stores page in the dashboard does the same things, and each control shows the c3 state command it runs. Coding agents use the MCP tools state_create, state_list, state_show, state_delete, state_keys, state_get, state_put and state_delete_key; see MCP server.
The API is /v2/state, with the same credentials as the CLI:
| Method and path | CLI |
|---|---|
POST /v2/state with {"name"} | c3 state create |
GET /v2/state | c3 state ls |
GET /v2/state/<store> | c3 state show |
DELETE /v2/state/<store> | c3 state rm |
GET /v2/state/<store>/keys?prefix=&cursor=&limit= | c3 state keys |
GET /v2/state/<store>/keys/<key> | c3 state get |
PUT /v2/state/<store>/keys/<key> with {"value", "if_version"?, "if_absent"?} | c3 state put |
DELETE /v2/state/<store>/keys/<key>?if_version= | c3 state del |
URL-encode the key, including any /.
Limits
| Limit | Beta value |
|---|---|
| Live stores per organisation | 20 |
| Key size | 512 bytes |
| Value size (as JSON) | 64 KB |
| Keys per store | 10,000 |
| Data per store | 100 MB |
| Requests | 600 per minute per user |
Going over a size or count limit returns STATE_LIMIT_EXCEEDED naming the limit. Going over the request rate returns RATE_LIMITED; the CLI waits and retries up to three times. State stores are free during the beta.
Errors
| Code | Meaning | What to do |
|---|---|---|
STATE_ACCESS_REQUIRED | Your account is not in the beta | Ask for access |
STATE_STORE_NOT_FOUND | No live store with that name in your organisation | c3 state ls, or c3 state create |
STATE_STORE_EXISTS | The name is already taken | Pick another name, or use the existing store |
STATE_KEY_NOT_FOUND | The key does not exist | c3 state keys <store> |
STATE_CONFLICT | A conditional write or delete did not match; nothing changed | Read the key again and retry with the new version |
STATE_LIMIT_EXCEEDED | A limit above was exceeded | Store less, or keep large data in a dataset |
RATE_LIMITED | Over 600 requests a minute | Slow down; retry after Retry-After |