Simulate a change to a referenced document
What a proposed body for a referenced document, such as a rulebook’s new rules, would flip before you write it. A
simulation job counts the in-scope judged documents that point at
the document, samples sample of them with known weights, and
evaluates the current and the proposed rendering against the same snapshot and engine epoch. Its simulation gives, per named
threshold, the sampled flips each way and the estimated population
flips with a 95% interval (never a bare zero), example ids that
flipped, what was left out, and the estimate of the real fan-out.
larger_sample offers a bigger sample when the interval cannot
decide. It writes nothing, and it is free. It takes the
suggest_parts daily limits (rate_limited with details.limit
and details.resets_at). relation must read a referenced
document; anything else is invalid_request.
Authorizations
An organization API key. Keys carry a role (read_write or
read_only) and may be restricted to a namespace prefix such as
acme/*, or to one namespace such as acme/prod/tenant_1. A prefix
matches on a / boundary: acme/prod/tenant_1* covers
acme/prod/tenant_1 and everything under acme/prod/tenant_1/,
never acme/prod/tenant_12.
Headers
One key per logical request, reused only on its retries. A key
belongs to one request: within your organization, the same method,
path, query and body. For 24 hours after a successful response, a
request with the key and the same body gets that response back
verbatim, with Idempotent-Replayed: true, and runs nothing. Only a
successful response is kept, so the retry of a request that failed
runs again. While the first request runs or its response is kept,
the key with a different request is idempotency_key_reused (422).
A request sent while one with its key is still running is
rate_limited with Retry-After: 1, without running: retry it to
get the first one's response. In the rare case the key can't be
checked, the request runs as if it had none.
1 - 255Path Parameters
The namespace name, with any / sent as %2F.
Up to 256 bytes. / separates levels of the hierarchy, as in acme/prod/tenant_123. Never exactly . or .., which a URL path can't carry.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+$A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..
1 - 128^[A-Za-z0-9_-]+$Body
A proposed body for a referenced document.
A relation of the judgment that reads a referenced document.
1 - 128^[A-Za-z0-9_-]+$The proposed document, as an upsert would write it. id names the referenced document.
Judged documents to evaluate both ways.
1 <= x <= 1000Response
The simulation job. Its simulation fills in when it is done.
A job. A shadow job comes from activating a differing
version without force. It starts in awaiting_confirm and
runs its sample while it waits; report fills in when the sample is
done. confirm activates version and the job ends done; cancel
leaves the active version unchanged. On a template prefix, namespace
is the prefix. A reference_index job builds the index
an entity judgment's relations need; it starts running, and
attribute names the attribute it indexes. An evaluation_export
job starts running, counts evaluations written in
progress.documents_done, never spends, and has export.
A resync job re-renders the readers of a changed threshold (resync) and re-judges the documents whose rendering flipped; a group_build job computes a new group's or aggregate's
first aggregates with no fan-out (group); a discover job fills
in proposal; a simulation job fills in simulation. Each starts running; discover and simulation never
spend. Fan-out is not a job: it runs within the judgment's rolling
limit and is deferred past it.
backfill, shadow, periodic, namespace_delete, reference_index, evaluation_export, resync, group_build, discover, simulation estimating, awaiting_confirm, running, paused, done, failed, cancelled A namespace name, or a template prefix: a namespace path ending in
/*, such as acme/prod/*, which every namespace under acme/prod/
inherits judgments from. Up to 256 bytes. Never exactly
. or .., which a URL path can't carry.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$Judging billed by this job so far, in US dollars.
x >= 0RFC 3339, UTC.
RFC 3339, UTC.
A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..
1 - 128^[A-Za-z0-9_-]+$RFC 3339, UTC.
Only on reference_index jobs, as attributes.<name>. The attribute whose reference index the job builds. Null for other jobs.
^attributes\.[A-Za-z0-9_-]+$Only on resync jobs.
Only on group_build jobs, the group whose aggregates it computes.
1 - 128^[A-Za-z0-9_-]+$Only on discover jobs; null until done.
Only on simulation jobs; null until done.
Shadow jobs only. The version being activated.
x >= 1Shadow jobs only. Null while the sample runs; progress counts the
sampled documents. A composite version's job has a
CompositeShadowReport, and when it has too few labels it
fails with an error that starts with insufficient_labels.
- Option 1
- Option 2
evaluation_export jobs only: the range, the evaluations written, and once done the download links.