Skip to content

Poll a background view run

GET
/api/v1/views/runs/{runId}
curl --request GET \
--url http://localhost:11044/api/v1/views/runs/example \
--header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Where a view run started with background=true stands, as the envelope a synchronous invoke returns: WAITING_INPUT with the quote in choice while it waits for its owner’s answer, RUNNING while it runs, and the view’s own result once it settles.

runId
required
string

The run id: the executionId of the envelope the background invoke returned

The run’s envelope

Media typeapplication/json

The result of invoking a named lens or view: its status and outcome, the data, and stable warning and error codes, never the query or script behind it

object
choice

Only on a WAITING_INPUT envelope from a background run: the quote its owner must answer before it runs

object
answer
required

Where the answer goes: POST {“choice”: “<an option’s value>”}; only the run’s owner may answer

string
expiresAt

Epoch milliseconds after which the question lapses unanswered and nothing runs

integer format: int64
options
required

The answers the question takes

Array<object>

One answer a background run’s question takes

object
label
required

What to show for this answer

string
value
required

The value to post as the answer

string
question
required

What the run would cost and the question put to its owner, e.g. the calls it would make to a named source

string
columnSources

Each result column and the plain expression that computed it, where that can be stated without exposing the query

object
key
additional properties
string
contractVersion
required

This envelope’s contract version, so a consumer can pin the shape

string
data

The result as nested JSON; null when there is no data (see outcome)

object
array
boolean
bigDecimal
boolean
bigInteger
boolean
binary
boolean
boolean
boolean
container
boolean
double
boolean
embeddedValue
boolean
empty
boolean
float
boolean
floatingPointNumber
boolean
int
boolean
integralNumber
boolean
long
boolean
missingNode
boolean
nodeType
string
Allowed values: ARRAY BINARY BOOLEAN MISSING NULL NUMBER OBJECT POJO STRING
null
boolean
number
boolean
object
boolean
pojo
boolean
short
boolean
string
boolean
textual
boolean
valueNode
boolean
dataContract

For a view bound to an ODCS data contract, the verdict its result was checked to

object
apiVersion
required

The ODCS apiVersion the contract declares, such as v3.1.0; v3.1.0 when the view was refused before it ran

string
available
required

False when the view could not run under its contract: the pinned contract or its object is missing, or its status forbids it. Then no rows are returned, whatever the mode

boolean
blocksRows
required
boolean
checkedAt
required

ISO-8601 instant the result was checked

string
checks
required

Each check made, in the order it was made

Array<object>

One check made when a view’s result was evaluated against its data contract

object
kind
required

schema, quality, freshness, status, binding or execution

string
message

What it found, in words, naming rows and fields but never their values; null when there is nothing to say

string
ruleId
required

The contract’s own id for a quality or freshness rule, or an embabel: id for a check the runtime makes itself, such as embabel:schema, embabel:binding or embabel:status

string
scope

invocation for the schema check, which covers this one result; null for every other check

string
verdict
required

PASS, WARN, FAIL, or UNKNOWN when the check could not be made

string
Allowed values: PASS WARN FAIL UNKNOWN
id
required

Id of the governing contract, as the view’s binding pins it

string
mode
required

observe or enforce, from the view’s binding

string
Allowed values: observe enforce
object
required

The contract object the rows were checked against, as the binding names it

string
status
required

The contract’s ODCS status, such as active, deprecated or retired; unavailable when the pinned contract is not in the world

string
verdict
required

The worst of the checks: FAIL if any failed, else UNKNOWN if any could not be made, else WARN if any warned, else PASS

string
Allowed values: PASS WARN FAIL UNKNOWN
version
required

The pinned contract version

string
error

Present only on a failed or refused outcome: a stable code and a message written to be shown

object
code
required

A stable, machine-readable code, e.g. FAN_OUT_OVER_BUDGET, FETCH_CAPPED, VIEW_QUERY_INVALID, CANCELLED

string
message
required

What happened and what would change it, safe to show; names no query, index or internal label

string
reason

Why a lookup that read records answered none, where a caller may act on it (FETCHED_NOT_MATCHED or UNPUSHED_FILTER); on a TOO_BROAD stopped at a fixed budget, which budget (MATCH_WORK, HELD_ROWS, STATEMENT_TIME, EXPRESSION_COST, STATEMENT_SHAPE, FETCHED_RECORDS, DERIVED_PAIRS, DERIVATION_ROUNDS, GRAPH_HEAP), or UNBOUNDED when nothing bounded a source it reads; null otherwise

string
executionId
required

Server-minted id of this execution; for a background run, the run id to poll, answer or stop it by

string
metrics
required

Coarse execution metrics: duration and call counts, never the calls themselves

object
cacheHit

Whether the answer was served from cache, when known

boolean
derivationMs

Milliseconds spent pricing and evaluating those rule sets, when any ran

integer format: int64
derivedFacts

Facts DERIVE rule sets concluded for this answer, when any ran

integer format: int64
durationMs
required

Wall-clock milliseconds the execution took

integer format: int64
externalCalls
required

Calls made to external data sources, as a count

integer format: int32
semanticCalls
required

Relevance searches made for a semantic anchor, as a count

integer format: int32
operationId
required

The lens id or view name that was invoked

string
outcome
required

Why the result is what it is: OK, EMPTY, PARTIAL, SOURCE_UNAVAILABLE, TOO_BROAD, TOO_EXPENSIVE, NOT_PERMITTED, UNTRUSTED_DATA, FAILED, or PENDING while a run has not settled

string
Allowed values: OK EMPTY PARTIAL SOURCE_UNAVAILABLE TOO_BROAD TOO_EXPENSIVE NOT_PERMITTED UNTRUSTED_DATA FAILED PENDING
outputType

The declared output type of data (rows, or a lens’s kind); null when there is no data

string
status
required

Lifecycle status: SUCCEEDED or FAILED for a synchronous call; RUNNING, WAITING_INPUT or CANCELLED only on the background surface

string
Allowed values: SUCCEEDED FAILED RUNNING WAITING_INPUT CANCELLED
warnings
required

Machine-readable warnings with stable codes; non-empty means the rows are not the whole story

Array<object>

A warning about a result: a stable code and a message that names no producer, index, label or query

object
code
required

A stable, machine-readable warning code, e.g. PARTIAL

string
message
required

What the warning means for these rows, safe to show

string

Example

{
"data": {
"nodeType": "ARRAY"
},
"dataContract": {
"checks": [
{
"verdict": "PASS"
}
],
"mode": "observe",
"verdict": "PASS"
},
"outcome": "OK",
"status": "SUCCEEDED"
}

Not authenticated. The filter chain answers an ApiError; a principal that resolves to no user answers the refusal

One of:

A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead

object
error
required

Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have

string

Example generated

{
"error": "example"
}

No background view run of this id belongs to the caller; another user’s run answers the same

Media typeapplication/json

A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead

object
error
required

Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have

string

Example generated

{
"error": "example"
}