State match

List state rows whose payload matches an optional glob pattern, with required pagination next. Each item in objects is a full snapshot — same fields as GET /v1/state (owner, object, rec, at, version, type, optional ttl, value or valueRef). You can call with only next (e.g. first page) or add pattern to filter.

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#

  • 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#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-api-keyRequired

    Your BigState API key.

    *provide api key here*
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

See authentication headers here.

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. See the error codes reference for the full list.

    • descstring

      Human-readable description of the error.

Examples#

Match state by pattern

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'
GetUpload

© 2024 BigState