Skip to main content
Are you a large language model? This page is available as raw markdown at /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:

FlagWrites only if
--if-version Nthe key is still at version N
--if-absentthe 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 pathCLI
POST /v2/state with {"name"}c3 state create
GET /v2/statec3 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​

LimitBeta value
Live stores per organisation20
Key size512 bytes
Value size (as JSON)64 KB
Keys per store10,000
Data per store100 MB
Requests600 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​

CodeMeaningWhat to do
STATE_ACCESS_REQUIREDYour account is not in the betaAsk for access
STATE_STORE_NOT_FOUNDNo live store with that name in your organisationc3 state ls, or c3 state create
STATE_STORE_EXISTSThe name is already takenPick another name, or use the existing store
STATE_KEY_NOT_FOUNDThe key does not existc3 state keys <store>
STATE_CONFLICTA conditional write or delete did not match; nothing changedRead the key again and retry with the new version
STATE_LIMIT_EXCEEDEDA limit above was exceededStore less, or keep large data in a dataset
RATE_LIMITEDOver 600 requests a minuteSlow down; retry after Retry-After