List object states

State is a timestamped and versioned value associated with an object. It can be stored inline or refer to uploaded binary data through a valueRef, and consumers can read the latest version or a specific historical one.

List state snapshots visible to the current API key, optionally filtered by a glob-style pattern. Each item in objects has the same shape as Get object state, including identity, timestamps, version, payload type, optional ttl, and either value or valueRef.

Pagination requires next: start with next=0, then pass each returned cursor to the next request until the API returns -1. If a pattern returns no rows, retry without it to distinguish a filter mismatch from missing state.

Use List objects when you need definitions rather than state snapshots, or Set object state to write a new value.

GET

{{host}}/v1/state/match?next={{next}}&pattern={{pattern}}

VERB:GET

BASE URL:{{host}}/v1/state/match

QUERY STRING:?next={{next}}&pattern={{pattern}}

Query parameters#

RequiredOptional

nextnumber
Required
Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.
example: 0
patternstring
Optional
Optional glob-style pattern to filter.
Values
- pattern
- *pattern
- pattern*
- *pattern*
example: *

Headers#

RequiredOptional

Send these headers with the request. Names are case-insensitive per HTTP rules.

x-api-keyRequired
Your BigState API key.
{{apiKey}}
Content-TypeRequired
MIME type of the request body.
application/json
AcceptRequired
MIME types the client can understand in the response.
application/json

Need a session token? See Token sign in.

Response parameters#

200Response body · object
Success. Returns a pagination cursor and full state rows for each match on this page — same fields as `GET /v1/state` (`owner`, `object`, `rec`, `at`, `version`, `type`, optional `ttl`, and `value` or `valueRef`).
```
{
  "next": 0,
  "objects": [
    {
      "owner": "Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6",
      "object": "Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6:position@Z5H1QxoGRz5vc6VeNIwwpVC6biVkYTqXe9SGQJJ6",
      "rec": "2026-03-31T13:54:39.1271586+00:00",
      "at": "2026-03-31T13:54:39.1271587+00:00",
      "version": 43,
      "type": 2,
      "ttl": 600,
      "value": {
        "lat": 32,
        "lng": 12
      }
    }
  ]
}
```
- nextnumber
  Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.
  example: 0
- objectsarray[object]
  State snapshots that matched the pattern on this page — each row matches the `GET /v1/state` response shape (`type`, optional `ttl`, etc.).
  - objects[0].ownerstring
    Owner identifier for this object.
  - objects[0].objectstring
    Fully qualified object name (name@owner).
  - objects[0].recstring
    Server record timestamp for this state row (ISO 8601 with offset).
  - objects[0].atstring
    Logical timestamp of the state value (ISO 8601 with offset).
  - objects[0].versionnumber
    Version number of this state snapshot.
  - objects[0].typenumber
    How the state payload is encoded — same numbering as the object definition `type` and POST /v1/state `value`.
    Values
    2 — JSON object
    3 — number
    4 — string
    5 — Base64 binary data
    example: 2
  - objects[0].ttlnumber
    Optional. Time-to-live for this state row in seconds, when one was set on write.
    example: 600
  - objects[0].valueany
    Inline state payload; shape follows the object’s value type (see object definition `type`).
    Values
    2 — JSON object
    3 — number
    4 — string
    5 — Base64 binary data
  - objects[0].valueRefstring
    Reference to externally stored payload when the object uses reference-backed state.
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
400Response body · object
Bad request.
```
{
  "error": 6,
  "desc": "Invalid request"
}
```
- errornumber
  Numeric error code. Use the response `desc` field for the human-readable explanation.
- descstring
  Human-readable description of the error.

Examples#

List object states

List state rows matching a glob pattern; each element matches the GET /v1/state shape (paginated with `next`), including optional `ttl` on each row when set.


curl https://api.bigstate.dev/v1/state/match?next=0&pattern=*position* \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Get state Value

Description
Query parameters
Headers
Response parameters
Examples