Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-reference.scale.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Create Multi-Stage Task

This endpoint creates a multistage task. Multi-stage tasks are designed to handle complex full-scene labeling that spans multiple annotation types and modalities, and serves as a replacement for Scale’s legacy dependent tasks system (which requires using multiple tasks to fully label a scene). Use cases for multi-stage tasks include but are not limited to:
  • Linking 3D cuboids to their 2D bounding box/polygon projections
  • Linking 3D cuboids to relevant top-down annotations
  • Conditional labeling (e.g. categorizing scenes based on localization quality to determine whether to label them)
The required parameters for this task are project, attachments, and scene_format.
 The callback_url is the URL which will be POSTed on task completion, and is described in more detail in the Callback section. Scale supports the following attachment types for multi-stage tasks:
  • (Recommended) Sensor Fusion Scene (.SFS)
  • LiDAR frames (.JSON)
​
Body Params
object
​
project
string
required
The name of the project to associate this task with. See the Projects Section for more details.
​
batch
string
The name of the batch to associate this task with. Note that if a batch is specified, you need not specify the project, as the task will automatically be associated with the batch’s project. For Scale Rapid projects specifying a batch is required. See Batches section for more details.
​
instruction
string
A markdown-enabled string or iframe embed google doc explaining how to do the task. You can use markdown to show example images, give structure to your instructions, and more.
​
callback_url
string
The full url (including the scheme http:// or https://) of the callback when the task is completed. See the Callback section for more details about callbacks.
​
attachments
array of strings
required
URLs to the scene attachments. Can be a single URL for .SFS attachments, or one URL per frame for .JSON attachments.
​
scene_format
string
required
Describes what type of file the attachment is. Can be sensor_fusion for .SFS attachments or split_base64 for .JSON attachments
​
task_blueprint_id
string
The ID of the blueprint that you would like to use when creating the multi-stage task. If no blueprint is specified, Scale will default to using the project’s most recent active blueprint.
​
metadata
object
A set of key/value pairs that you can attach to a task object. It can be useful for storing additional information about the task in a structured format. Max 10KB.
​
unique_id
string
A arbitrary ID that you can assign to a task and then query for later. This ID must be unique across all projects under your account, otherwise the task submission will be rejected. See Avoiding Duplicate Tasks for more details.
​
priority
integer
A value of 10, 20, or 30 that defines the priority of a task within a project. The higher the number, the higher the priority.
​
clear_unique_id_on_error
boolean
If set to be true, if a task errors out after being submitted, the unique id on the task will be unset. This param allows workflows where you can re-submit the same unique id to recover from errors automatically
​
tags
array of strings
Arbitrary labels that you can assign to a task. At most 5 tags are allowed per task. You can query tasks with specific tags through the task retrieval API.
import requests

# Replace with your actual API key
API_KEY = "your_api_key_here"

# Define the URL for the API endpoint
url = "https://api.scale.com/v1/task/multistage"

# Define the payload for the multi-stage task
payload = {
    "project": "your_project_name_here"
    "instruction": "Annotate the *vehicles* and *pedestrians* in the scene.",
    "callback_url": "https://example.com/callback",
    "attachments": ["https://static.scale.com/uploads/pandaset-demo/scene.sfs"],
    "scene_format": "sensor_fusion",
    "priority": None
}

# Set up the headers for the request
headers = {
    "accept": "application/json",       # Specify that we want the response in JSON format
    "content-type": "application/json"  # Specify the content type of the request
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

{
  "callback_url": "http://www.example.com/callback",
  "created_at": "2024-01-16T21:03:33.166Z",
  "instruction": "Annotate the *vehicles* and *pedestrians* in the scene.",
  "is_test": false,
  "params": {},
  "status": "pending",
  "task_id": "5a99e20de50d4979ce6d291e",
  "type": "multistage"
}