Tasks Object Overview

A task represents an individual unit of work to be done by a Tasker. There's a 1:1 mapping between a task and the data to be labeled. For example, there'd be 1 task for each image, video, or lidar sequence needing to be labeled.

You specify how the labeling should be done for a given task when making an API call specifying a set of task parameters to the endpoint you'd like to leverage.

Tasks have a type such as "Image Annotation", "Video Annotation", "Lidar Segmentation", or "Document Transcription".

Learn more about our key concepts and workflows in our "Scale 101" guides.


Looking to create your first Task?

Scale has many types of tasks. Get the details for the specific type of task you want to create from the navigation bar. For example, if you have images to label, check out the "Scale Image" section.

Not sure which task type is right for you? Consult our visual guide to find out.

Task Properties

  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "updated_at": "2016-06-23T09:10:02.798Z",
  "completed_at": "2016-06-23T09:10:02.798Z",  
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
  "callback_url": "http://www.example.com/callback",
  "callback_completed": true,
  "response": {
    "category": "big"
  "metadata": {},
  "audits": [
      "audited_by": "[email protected]",
      "audited_at": "2016-06-24T15:32:03.585Z",
      "audit_time_secs": 120,
      "audit_result": "accepted",
      "audit_source": "customer"
      "audited_by": "[email protected]",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 511,
      "audit_result": "fixed",
      "audit_source": "scale"
  "tags": ["experiment_1", "owner:david"],
  "unique_id": "product_experiment_dg3d9x83"
task_idstringThe task_id is the unique identifier for the task.
typestringThe type of the task, for example, imageannotation or lidarsegmentation
instructionstringA markdown-enabled string explaining the instructions for the task.

You can use markdown to show example images, give structure to your instructions, and more. HTML tags are unsupported.
paramsobjectAn object with the parameters of the task based on the type.

For imageannotation type tasks, for example, this will include attachment, and geometries.
responseobjectAn object corresponding to the response once the task is completed. Each task type has its response format documented.
callback_urlstringA string of the URL that should be POSTed once the task is completed for the response data. See the Callback section for more details.
statusstringThe status of the task, one of pending, completed, canceled or error.
created_attimestampA string of the UTC timestamp for when the task was created.
updated_attimestampA string of the UTC timestamp for when the task was last updated.

If a task is completed, this timestamp is usually the same as the completed_at timestamp. However, sometimes a task can be redone, and updated after its completion.
completed_attimestampA string of the UTC timestamp for when the task was completed. This will only be filled in after it is completed.
callback_completedbooleanA boolean stating whether or not the callback succeeded. If the callback returns with a 2xx status code, the value will be true. If the callback fails to return a 2xx status code through all retries, then the value will be false.
customer_review_statusstringThe status of the QA'd task, one of pending, accepted, fixed or rejected.
times_redonenumberA counter for the number of times the task has been redone. It will be present if the task has been redone at least once.
metadataobject, default {}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. See Task Metadata for more information.
project_param_versionnumber | nullCorresponds to the project version a task was created with, or null if no project version exists.
auditsarray, default []An array of audit records.
unique_idstring, optionalA 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.
tagsarray, optionalArbitrary 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.