Poll a background view run
const url = 'http://localhost:11044/api/v1/views/runs/example';const options = {method: 'GET', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The run id: the executionId of the envelope the background invoke returned
Responses
Section titled “Responses”The run’s envelope
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
Only on a WAITING_INPUT envelope from a background run: the quote its owner must answer before it runs
object
Where the answer goes: POST {“choice”: “<an option’s value>”}; only the run’s owner may answer
Epoch milliseconds after which the question lapses unanswered and nothing runs
The answers the question takes
One answer a background run’s question takes
object
What to show for this answer
The value to post as the answer
What the run would cost and the question put to its owner, e.g. the calls it would make to a named source
Each result column and the plain expression that computed it, where that can be stated without exposing the query
object
This envelope’s contract version, so a consumer can pin the shape
The result as nested JSON; null when there is no data (see outcome)
object
For a view bound to an ODCS data contract, the verdict its result was checked to
object
The ODCS apiVersion the contract declares, such as v3.1.0; v3.1.0 when the view was refused before it ran
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
ISO-8601 instant the result was checked
Each check made, in the order it was made
One check made when a view’s result was evaluated against its data contract
object
schema, quality, freshness, status, binding or execution
What it found, in words, naming rows and fields but never their values; null when there is nothing to say
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
invocation for the schema check, which covers this one result; null for every other check
PASS, WARN, FAIL, or UNKNOWN when the check could not be made
Id of the governing contract, as the view’s binding pins it
observe or enforce, from the view’s binding
The contract object the rows were checked against, as the binding names it
The contract’s ODCS status, such as active, deprecated or retired; unavailable when the pinned contract is not in the world
The worst of the checks: FAIL if any failed, else UNKNOWN if any could not be made, else WARN if any warned, else PASS
The pinned contract version
Present only on a failed or refused outcome: a stable code and a message written to be shown
object
A stable, machine-readable code, e.g. FAN_OUT_OVER_BUDGET, FETCH_CAPPED, VIEW_QUERY_INVALID, CANCELLED
What happened and what would change it, safe to show; names no query, index or internal label
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
Server-minted id of this execution; for a background run, the run id to poll, answer or stop it by
Coarse execution metrics: duration and call counts, never the calls themselves
object
Whether the answer was served from cache, when known
Milliseconds spent pricing and evaluating those rule sets, when any ran
Facts DERIVE rule sets concluded for this answer, when any ran
Wall-clock milliseconds the execution took
Calls made to external data sources, as a count
Relevance searches made for a semantic anchor, as a count
The lens id or view name that was invoked
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
The declared output type of data (rows, or a lens’s kind); null when there is no data
Lifecycle status: SUCCEEDED or FAILED for a synchronous call; RUNNING, WAITING_INPUT or CANCELLED only on the background surface
Machine-readable warnings with stable codes; non-empty means the rows are not the whole story
A warning about a result: a stable code and a message that names no producer, index, label or query
object
A stable, machine-readable warning code, e.g. PARTIAL
What the warning means for these rows, safe to show
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
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
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
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some: a sentence, such as the fields a body may carry, or an object of machine fields in the server’s own words, such as api_approval_unapprovable’s reason (the declaration reader’s code, MALFORMED or FIELD_INVALID), field (where it points, [0].headers[1] or apis/spec.json#/paths/~1things/post) and rule (the sentence the reader states for it), or a refused Realm capture’s reason (SYMLINK, TOO_LARGE, …) and file (the path relative to the Realm root); never the caller’s or a Realm’s text; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "error": "example"}No background view run of this id belongs to the caller; another user’s run answers the same
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
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
Example generated
{ "error": "example"}
