Workflow stages and tasks
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.
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
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
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