Get a calc rule's live state

GET

/calc-rules/{name}/state

const url = 'https://example.com/api/v1/calc-rules/example/state?limit=100';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/api/v1/calc-rules/example/state?limit=100'

What a calc rule last did on each owner the caller may read (components by the component read scope, systems by the system read scope), each owner named now: the value it computed, when and at which version, the inputs it found no value of, a system’s members that held none and the instances it left out as stale (named when the caller may read the component, else counted), an error, since when a system has had no members, and whether the owner is pending (with when a deferred mark is due). Ordered on the server, failing owners first, then pending, then those it wrote nothing for, then those holding a value, each by name, and at most limit of them; total and the pending depth count every owner the caller may read, listed or not. Gated by rule:read.

Parameters

Path Parameters

name

required

The rule’s name (its uuid is accepted too)

string

The rule’s name (its uuid is accepted too)

Query Parameters

limit

The most owners to list, in state order: failing, pending, missing an input (or with no members), valued, each by name

integer format: int64

default: 100 >= 1 <= 1000

The most owners to list, in state order: failing, pending, missing an input (or with no members), valued, each by name

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

owners

required

The rule’s state on the owners the caller may read, at most limit of them: failing first, then pending, then those it wrote nothing for (an input missing, a system with no members), then those holding a value, each by name

Array<object> | null

object

computed_at

When the rule last computed on the owner; absent when it has not yet

string format: date-time

due_at

When a deferred mark (a failed computation backing off) is due

string format: date-time

error

Why the rule could not compute (a run-time failure, a reduce that no longer compiles, a database fault it is backing off from)

string

missing

required

The input keys no value was found for (nothing was written)

Array<string> | null

no_members_since

A system with no role-bound members since then: the rule writes nothing and its last value stands, unsupported

string format: date-time

owner

required

The owner, by name, resolved now

string

owner_id

required

The owner’s uuid

string

owner_kind

required

What the owner is

string

Allowed values: component system

pending

required

The owner is marked for the next tick

boolean

rule_version

The rule version that computed it

integer format: int64

skipped

required

A system rule’s members that held no value of an input, those the caller may read

Array<object> | null

object

component

required

The member component, by name

string

component_id

required

The member component’s uuid

string

key

required

The input key the member held no value of

string

skipped_hidden

required

How many more skipped members the caller may not read (counted, never named)

integer format: int64

stale

required

The instances an input’s list left out as stale, on components the caller may read

Array<object> | null

object

component

required

The component the instance is on, by name

string

component_id

required

The component’s uuid

string

instance

required

The instance left out as stale

string

key

required

The input key

string

stale_hidden

required

How many more stale instances are on components the caller may not read

integer format: int64

value

The value the rule last computed on the owner; absent when it could not compute

pending_depth

required

How many of those owners are pending, listed or not (only owners the caller may read are counted)

integer format: int64

total

required

How many owners the caller may read the rule has state or a mark on, listed or not

integer format: int64

Example

{
  "$schema": "/api/v1/schemas/CalcRuleStateOutputBody.json",
  "owners": [
    {
      "owner_kind": "component"
    }
  ]
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

Example

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}