Skip to content
Embabel Worlds

Start a slow, resumable fill of an expensive materialization

POST
/api/v1/admin/kg/fills
curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/fills \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "budgetPerTick": 1, "cypher": "example", "label": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
username
string

Username to act as; when it resolves to a user it is used in preference to the authenticated principal. Omitted or blank, the authenticated principal acts; 401 when neither resolves

Request Bodyrequired

Section titled “Request Bodyrequired”

The fill to start, owned by the acting user: cypher (required, 400 when blank) is the query the scheduler re-runs one chunk per tick until a pass makes no live call; budgetPerTick caps live producer calls per chunk, default 60, clamped to 1–500; label names the fill in progress and activity, and the fill’s id stands in when it is blank

Media typeapplication/json

What to fill: the body of POST /admin/kg/fills

object
budgetPerTick
required

Units of paid work one tick may buy: a producer fetch group or a group of an inline model judgement, not HTTP requests or tokens. Clamped to 1-500; defaults to 60 when absent

integer format: int32
cypher
required

The Virtual Cypher query whose materialization the fill drives; every tick re-runs it. Blank is a 400

string
label
required

Display name for the fill, shown in its activity; empty when absent, and the fill id is shown instead

string

Example generated

{
  "budgetPerTick": 1,
  "cypher": "example",
  "label": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The fill, as started — carrying a warning when its producers cannot outlive the sweep, so it will poll rather than converge

Media typeapplication/json

A fill: a slow, resumable materialization of one query, re-run a budgeted chunk per tick until a pass buys nothing. What /admin/kg/fills starts and lists.

object
budgetPerTick
required

Units of paid work one tick may buy — a producer fetch group or a group of an inline model judgement, not HTTP requests or tokens. Clamped to 1–500; defaults to 60.

integer format: int64
cypher
required

The Cypher every tick re-runs, as it was submitted.

string
id
required

The fill’s id, fill_ plus 12 hex characters — what DELETE /admin/kg/fills/{id} takes.

string
label
required

A display name for the fill. Empty when none was given.

string
progress
required

How far the fill has got, as of its most recent tick.

object
coverage
required

Keys the producer caches answer, of the total the last pass enumerated. keysTotal is null where the query has no denominator; never derive a fraction then.

object
fractionResolved
number format: double
keysResolved
required

Distinct key units, one per producer, key and period, answered in the execution from a cache tier or a successful fetch

integer format: int64
keysTotal

Distinct key units the execution demanded; null when the sweep has no denominator (totality UNKNOWN), which never means zero

integer format: int64
totality
required
string
Allowed values: KNOWN UNKNOWN
createdAt
required

Epoch milliseconds at which the fill was started.

integer format: int64
lastError

Why the most recent tick failed or was refused. Null when it ran clean. An error leaves the fill RUNNING.

string
lastTickAt

Epoch milliseconds of the most recent tick, refused ones included. Null before the first.

integer format: int64
liveCallsLastTick
required

Paid calls in the most recent tick alone, counted as liveCallsTotal counts them.

integer format: int64
liveCallsTotal
required

Paid calls across every tick: producer fetches, in-query model calls and semantic searches.

integer format: int64
state
required

RUNNING, DONE (a full pass needed no paid work) or CANCELLED.

string
ticks
required

Chunks run so far. A chunk refused before it ran — a halt, a ceiling — does not count.

integer format: int64
trend
required
string
Allowed values: UNKNOWN CONVERGING NOT_CONVERGING
routine

The routine the fill runs as, whose agent governs every chunk. Null for a fill an operator started outside any routine run.

string
userId
required

The id of the user the fill belongs to and runs as.

string
warning

Why this fill will keep polling rather than reach DONE — its producers’ records do not outlive a sweep. Decided at start. Null when it can converge, or when the query could not be planned to say.

string

Example 

{
  "progress": {
    "coverage": {
      "totality": "KNOWN"
    },
    "trend": "UNKNOWN"
  }
}

400

Section titled “400”

Cypher is required: a fill needs the materialization it is filling

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}

401

Section titled “401”

No authenticated principal and no resolvable username

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}