Documentation preview

Tasks, runs & results

Four records keep reusable inputs separate from execution history and saved responses.

The four service records

RecordResponsibility
tasksReusable prompt filename, JSON arguments, and optional string unit ID.
runsA selected task batch with a stored model and reasoning setting.
attemptsOne execution attempt for a task in a run, including its state and diagnostics.
resultsSaved successful response text for a run/task pair.

Tasks are reusable inputs

A task does not carry a model or execution state. The same task IDs can be selected in several runs. The optional unit_id carries an application identifier as text; it is separate from the integer task ID.

Runs make inputs runnable

Store.create_run(model, reasoning, task_ids) creates the run and its initial pending attempts atomically. Execution uses that run's stored parameters, even if configuration defaults change later.

Attempts preserve history

Attempt lifecycleExample
pending → in_progress → completed / timeout / error

An explicit retry creates a new pending attempt after an error or timeout. Earlier attempts are retained. Successful tasks cannot be overwritten by a retry in the same run.

Results are saved responses

Successful response text and the completed attempt state are saved in one transaction. The result is associated with its run and task. Response text can contain JSON, but the integration must parse and validate it before application writes.

Completion is not delivery. A finished run can contain errors. A saved response does not mean that an application accepted or received it.