Create a task

  1. Request
  2. Headers
  3. Query parameters
  4. Request body
  5. Response

Creates a task.

You can send a maximum of 100,000 requests of this kind per minute and a maximum of 2,000,000 requests per day.

Request

POST https://toloka.yandex.com/api/v1/tasks
Authorization: OAuth <OAuth token>
Content-Type: application/JSON

{task data}

Headers

Title Overview
authorization A token for account authorization. Add OAuth as a prefix.
content-type Specifies the data format in the request body.
Title Overview
authorization A token for account authorization. Add OAuth as a prefix.
content-type Specifies the data format in the request body.

Query parameters

Specified in the link after the question mark; separated by &.

Parameter Overview

async_mode

boolean

Mode for request processing:

  • true — Asynchronous. Creates an asynchronous operation that runs in the background. The response contains information about the operation (start and completion time, status).

  • false — Synchronous. The response contains information about the created task.

The default value is false.

allow_defaults

boolean

Overlap settings:

The default value is false.

skip_invalid_items

boolean

Validation parameters for JSON objects:

  • true — Create a task that passed validation.

  • false — Stop the operation and don't create a task.

The default value is false.

open_pool

boolean

Open the pool immediately after creating a task, if the pool is closed. The default value is false.

operation_id

string

Operation ID for asynchronous task loading (if async_mode=true).

We recommend sending the ID in the POST request to avoid accidental errors, such as creating the operation multiple times for the same task.

The ID should conform to the RFC4122 standard.

You can use this ID in the future to get information about the operation.

Parameter Overview

async_mode

boolean

Mode for request processing:

  • true — Asynchronous. Creates an asynchronous operation that runs in the background. The response contains information about the operation (start and completion time, status).

  • false — Synchronous. The response contains information about the created task.

The default value is false.

allow_defaults

boolean

Overlap settings:

The default value is false.

skip_invalid_items

boolean

Validation parameters for JSON objects:

  • true — Create a task that passed validation.

  • false — Stop the operation and don't create a task.

The default value is false.

open_pool

boolean

Open the pool immediately after creating a task, if the pool is closed. The default value is false.

operation_id

string

Operation ID for asynchronous task loading (if async_mode=true).

We recommend sending the ID in the POST request to avoid accidental errors, such as creating the operation multiple times for the same task.

The ID should conform to the RFC4122 standard.

You can use this ID in the future to get information about the operation.

Request body

{
   "pool_id": "1",
   "input_values": {
      "image_url": "www.images/image1.ru"
   },
   "known_solutions": [
      {
         "output_values": {
            "result": "OK",
            "like": false
         },
         "correctness_weight": 0.8
      },
      {
         "output_values": {
            "result": "OK",
            "like": true
         },
         "correctness_weight": 1
      },
    ],
   "baseline_solutions": [
      {
         "output_values": {
            "result": "OK",
            "like": false
         },
         "confidence_weight": 0.8
      },
      {
         "output_values": {
            "result": "OK",
            "like": true
         },
         "confidence_weight": 1
      } 
   ], 
   "message_on_unknown_solution": "У кота хорошее настроение",
   "overlap": 3,
   "infinite_overlap": false,
   "reserved_for": [], 
   "unavailable_for": []
}
Copied to clipboard
Key Overview

pool_id

string | required

The ID of the pool that the task is uploaded to.

input_values

object | required

Input data for a task. List of pairs:

"<ID of field 1>": "<value of field 1>",
"<ID of field 2>": "<value of field 2>",
...
"<ID of field N>": "<value of field N>"

known_solutions[].output_values

object | required

Output data values to check. You should specify values for all required output data fields.

"<ID of field 1>": "<correct response>",
"<ID of field 2>": "<correct response>",
...         

baseline_solutions[].output_values

object | required

Output data values for preliminary responses.

"<ID of field 1>": "<preliminary response>",
"<ID of field 2>": "<preliminary response>",
...

baseline_solutions[].confidence_weight

float | required

Confidence in a response, from 0 to 1.

The default value is 1.

overlap

string | required if

Required if the parameter is not used when creating a task suite allow_defaults=true, and the overlap is not specified in the pool parameters (defaults.​default_​overlap_for_​new_task_suites).

Task suite overlap.

known_solutions[]

array of objects

Correct responses for control and training tasks.

You can specify several options for a correct task response.

If one option is more correct than another, you can assign different weights to the response options. To do this, use the correctness_weight key.

known_solutions[].correctness_weight

float

The weight of a correct response in the range from 0 to 1.

Lets you count a response as partially correct. This is convenient when there is no single right response to the task.

This works like awarding points: if you need to complete one control task correctly to get a skill (receive 1 point), you may complete one task with a weight of 1 or two tasks with a weight of 0.5 or higher.

The default value is 1.

baseline_solutions[]

array of objects

Preliminary responses. This data simulates performer responses when calculating confidence in a response. It is used in dynamic overlap (also known as incremental relabeling or IRL) and aggregation of results by skill.

Define output_values and confidence_weight for each preliminary response.

For example, you ask performers to label whether an image shows a cat or a dog. Suppose your neural network already determined that the image might show a dog with a probability of 80% and a cat with a probability of 40%. Let's say you set dynamic overlap from 1 to 3 and the minimum response confidence at 85%.

If the performer answers "Dog" and the confidence in their response is high, the overlap most likely won't increase because one response is enough. If the performer answers "Cat", the confidence is most likely not high enough and the overlap will increase further.

Can't be used when creating a task suite: an error with code 400 saying VALUE_NOT_ALLOWED will be returned to your request.

message_on_unknown_solution

string

Hint for the task (for training tasks).

infinite_overlap

boolean

Assigns tasks with infinite overlap. For instance, you can use this for training tasks when you want to assign them to all users:
  • true — Use infinite overlap.

  • false — Use the overlap that is set for the task or pool.

The default value is false.

origin_task_id

string

ID of the task it was copied from.

reserved_for[]

array of integer

IDs of users who will have access to the task.

unavailable_for[]

array of integer

IDs of users who shouldn't have access to the task.

Key Overview

pool_id

string | required

The ID of the pool that the task is uploaded to.

input_values

object | required

Input data for a task. List of pairs:

"<ID of field 1>": "<value of field 1>",
"<ID of field 2>": "<value of field 2>",
...
"<ID of field N>": "<value of field N>"

known_solutions[].output_values

object | required

Output data values to check. You should specify values for all required output data fields.

"<ID of field 1>": "<correct response>",
"<ID of field 2>": "<correct response>",
...         

baseline_solutions[].output_values

object | required

Output data values for preliminary responses.

"<ID of field 1>": "<preliminary response>",
"<ID of field 2>": "<preliminary response>",
...

baseline_solutions[].confidence_weight

float | required

Confidence in a response, from 0 to 1.

The default value is 1.

overlap

string | required if

Required if the parameter is not used when creating a task suite allow_defaults=true, and the overlap is not specified in the pool parameters (defaults.​default_​overlap_for_​new_task_suites).

Task suite overlap.

known_solutions[]

array of objects

Correct responses for control and training tasks.

You can specify several options for a correct task response.

If one option is more correct than another, you can assign different weights to the response options. To do this, use the correctness_weight key.

known_solutions[].correctness_weight

float

The weight of a correct response in the range from 0 to 1.

Lets you count a response as partially correct. This is convenient when there is no single right response to the task.

This works like awarding points: if you need to complete one control task correctly to get a skill (receive 1 point), you may complete one task with a weight of 1 or two tasks with a weight of 0.5 or higher.

The default value is 1.

baseline_solutions[]

array of objects

Preliminary responses. This data simulates performer responses when calculating confidence in a response. It is used in dynamic overlap (also known as incremental relabeling or IRL) and aggregation of results by skill.

Define output_values and confidence_weight for each preliminary response.

For example, you ask performers to label whether an image shows a cat or a dog. Suppose your neural network already determined that the image might show a dog with a probability of 80% and a cat with a probability of 40%. Let's say you set dynamic overlap from 1 to 3 and the minimum response confidence at 85%.

If the performer answers "Dog" and the confidence in their response is high, the overlap most likely won't increase because one response is enough. If the performer answers "Cat", the confidence is most likely not high enough and the overlap will increase further.

Can't be used when creating a task suite: an error with code 400 saying VALUE_NOT_ALLOWED will be returned to your request.

message_on_unknown_solution

string

Hint for the task (for training tasks).

infinite_overlap

boolean

Assigns tasks with infinite overlap. For instance, you can use this for training tasks when you want to assign them to all users:
  • true — Use infinite overlap.

  • false — Use the overlap that is set for the task or pool.

The default value is false.

origin_task_id

string

ID of the task it was copied from.

reserved_for[]

array of integer

IDs of users who will have access to the task.

unavailable_for[]

array of integer

IDs of users who shouldn't have access to the task.

Response

Depending on the async_mode value in the request, the response contains:

Information about the created task. Besides parameters that are set when creating a task, it includes parameters that are assigned to the task automatically:
Parameter Overview

id

string

Task ID.

origin_task_id

string

The ID of a task from another pool from which this task was copied for majority vote verification.

created

string

The UTC date and time when the task suite was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].

Parameter Overview

id

string

Task ID.

origin_task_id

string

The ID of a task from another pool from which this task was copied for majority vote verification.

created

string

The UTC date and time when the task suite was created, in ISO 8601 format: YYYY-MM-DDThh:mm:ss[.sss].