Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Workflow stages and tasks

Find a stage, enumerate its tasks, and perform role-appropriate task actions.

Outcome: Find a stage, enumerate its tasks, and perform role-appropriate task actions.

workflow = project.workflow
annotate = workflow.get_stage(name="Annotate")

for task in annotate.get_tasks():
    task.claim()
    task.set_priority(10)
    task.submit()

review = workflow.get_stage(stage_type="review")
for task in review.get_tasks():
    task.reject(reason="Boundary policy", comment="Exclude cast shadow")

Stage lookup accepts exactly one of stage_id, name, or stage_type. Task actions are claim, assign, release, set_priority, submit, approve, reject, skip, and move. The configured workflow determines which action is valid from the current stage.

Call or field
Behavior

workflow.stages

Every stage of the project's workflow, each with id, name, type, task_count, sort_order, and is_terminal.

workflow.get_task(task_id), client.get_workflow_task(task_id)

Fetch one task by its ID.

stage.get_tasks(include_unavailable=True)

Also list the tasks of the stage that are not currently available. Default False.

task.available_actions

Actions valid now: claim, assign, release, complete (sent by submit()), approve, reject, or skip. Filled when a task is fetched by ID or returned by an action; empty on tasks from get_tasks().

task.move_targets

One entry per stage with stage_id, stage_name, stage_type, and allowed. Filled when a task is fetched by ID or returned by an action; empty on tasks from get_tasks().

task.get_consensus_comparison()

On a Consensus review task (task_kind is consensus_review), return the compared submissions and a selection_options list. Any other task raises ValidationError.

task.copy_consensus_component(source_assignment_id=..., component_kind=..., component_locator=..., operation="add")

On a Consensus review task, copy one component into the review result. Take the three values from a selection_options entry. operation is add or replace; panel_id and replacement_locator are optional.

task.complete_model_run(run_id, result, model_version="")

For a geospatial task whose Model stage run delivers its result later, upload the final result: one GeoJSON FeatureCollection or a list of them.

task.fail_model_run(run_id, error)

Report that run as failed, with an error of at most 4,000 characters. The task stays in the Model stage.

Operating contract

Concern
Required behavior

Execution surface

Pinned unitlab==3.1.6 application environment on Python 3.10+.

Identity

Least-privilege API key supplied through approved configuration.

Target resolution

Stable resource IDs and an explicitly bounded target set.

Success evidence

Typed return fields, server-side state, and downstream acceptance of the result.

Failure and recovery boundary

Condition
Response

Authentication or authorization fails

Stop, correct the service identity or access model, rotate exposed credentials, and rerun a read-only check.

Validation or entitlement rejects the operation

Correct the input or entitlement; do not retry an unchanged request.

A request times out

Inspect remote state before repeating a mutation because the server may have accepted it.

Asynchronous processing exceeds its deadline

Preserve the Batch Queue or release ID, continue bounded monitoring, and inspect item-level failures.

Only part of a batch succeeds

Keep successful identifiers, isolate failed rows, and retry only the corrected subset.


Explore related Unitlab capabilities: Unitlab’s data annotation platform