v7.10
Clarifai Basics
API Guide
Portal Guide
Data Labeling Services
Product Updates
Additional Resources
Tasks
Group your labeling work into tasks that can be delegated.
The tasks are a powerful tool which can help your team to annotate inputs from your application.
Create
To create a new task in your app you
POST the task information to v2/task endpoint.Non-Assigned Task
A task should be assigned to a list of users, but it's not required. The following code will create a non-assigned task.
cURL
Javascript (REST)
1
curl -X POST \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "FULL"
12
},
13
"concept_ids": [
14
"{{concept_id}}"
15
],
16
"input_source": {
17
"type": "ALL_INPUTS"
18
},
19
"sample_ms": 1000,
20
"review": {
21
"strategy": "NONE"
22
}
23
}
24
]
25
}'\
26
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "FULL"
12
},
13
"concept_ids": [
14
"{{concept_id}}"
15
],
16
"input_source": {
17
"type": "ALL_INPUTS"
18
},
19
"sample_ms": 1000,
20
"review": {
21
"strategy": "NONE"
22
}
23
}
24
]
25
});
26
27
const requestOptions = {
28
method: 'POST',
29
headers: {
30
'Accept': 'application/json',
31
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
32
},
33
body: raw
34
};
35
36
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
37
.then(response => response.text())
38
.then(result => console.log(result))
39
.catch(error => console.log('error', error));
Copied!
Assigned Task
A task should be assigned to a list of users. These users will do the work, so they're also called workers. A task may also be assigned to a list of users for review.
cURL
Javascript (REST)
1
curl -X POST \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "FULL",
12
"user_ids": [
13
"{{worker_user_id}}"
14
]
15
},
16
"concept_ids": [
17
"{{concept_id}}"
18
],
19
"input_source": {
20
"type": "ALL_INPUTS"
21
},
22
"sample_ms": 1000,
23
"review": {
24
"strategy": "MANUAL",
25
"manual_strategy_info": {
26
"sample_percentage": 0.5
27
},
28
"user_ids": [
29
"{{reviewer_user_id}}"
30
]
31
}
32
}
33
]
34
}'\
35
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "FULL",
12
"user_ids": [
13
"{{worker_user_id}}"
14
]
15
},
16
"concept_ids": [
17
"{{concept_id}}"
18
],
19
"input_source": {
20
"type": "ALL_INPUTS"
21
},
22
"sample_ms": 1000,
23
"review": {
24
"strategy": "MANUAL",
25
"manual_strategy_info": {
26
"sample_percentage": 0.5
27
},
28
"user_ids": [
29
"{{reviewer_user_id}}"
30
]
31
}
32
}
33
]
34
});
35
36
const requestOptions = {
37
method: 'POST',
38
headers: {
39
'Accept': 'application/json',
40
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
41
},
42
body: raw
43
};
44
45
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
46
.then(response => response.text())
47
.then(result => console.log(result))
48
.catch(error => console.log('error', error));
Copied!
Task with Partitioned Worker Strategy
The previous tasks were created with full worker strategy.
1
{
2
"strategy": "FULL"
3
}
Copied!
In case of
FULL worker strategy, each worker will work on all inputs selected in the input source.If you wish the work to be distributed between workers, then you can select the
PARTITIONED worker strategy.In the following example:
- there are two workers
workers_per_input: each input will be assigned to 1 workerweights.{{user_id1}}: the first worker will get 90% of inputsweights.{{user_id2}}: the second worker will get 10% of inputs
cURL
Javascript (REST)
1
curl -X POST \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "PARTITIONED",
12
"user_ids": ["{{user_id1}}", "{{user_id2}}"],
13
"partitioned_strategy_info": {
14
"type": "WEIGHTED",
15
"workers_per_input": 1,
16
"weights": {
17
"{{user_id1}}": 90,
18
"{{user_id2}}": 10
19
}
20
}
21
},
22
"concept_ids": [
23
"{{concept_id}}"
24
],
25
"input_source": {
26
"type": "ALL_INPUTS"
27
},
28
"sample_ms": 1000,
29
"review": {
30
"strategy": "NONE"
31
}
32
}
33
]
34
}'\
35
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "PARTITIONED",
12
"user_ids": ["{{user_id1}}", "{{user_id2}}"],
13
"partitioned_strategy_info": {
14
"type": "WEIGHTED",
15
"workers_per_input": 1,
16
"weights": {
17
"{{user_id1}}": 90,
18
"{{user_id2}}": 10
19
}
20
}
21
},
22
"concept_ids": [
23
"{{concept_id}}"
24
],
25
"input_source": {
26
"type": "ALL_INPUTS"
27
},
28
"sample_ms": 1000,
29
"review": {
30
"strategy": "NONE"
31
}
32
}
33
]
34
});
35
36
const requestOptions = {
37
method: 'POST',
38
headers: {
39
'Accept': 'application/json',
40
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
41
},
42
body: raw
43
};
44
45
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
46
.then(response => response.text())
47
.then(result => console.log(result))
48
.catch(error => console.log('error', error));
Copied!
Notes:
- It is not required for the weights to add up to 100. For example, the weights [9, 1] are equivalent with weights [90, 10].
- The partitioning is approximate. This means that the number of assigned inputs to each worker may have a small error margin, but it will be close to the assigned weight percentage.
Task with Consensus Review
The previous tasks were created with no review or manual review strategy.
1
{
2
"strategy": "MANUAL"
3
}
Copied!
We recommend to create tasks with
CONSENSUS review strategy. When enough workers label an input in the same way, it will automatically be approved, with no need for the reviewer to spend time to check. In this way, the reviewer will be able to focus on the inputs where the workers don't agree.Note that an approval threshold must be set. For example, in case of 3 workers and
approval_threshold set to 2, if an input is labeled in the same way by 2 workers, they form a majority and the group reaches a consensus.cURL
Javascript (REST)
1
curl -X POST \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "PARTITIONED",
12
"user_ids": ["{{user_id1}}", "{{user_id2}}", "{{user_id3}}"],
13
"partitioned_strategy_info": {
14
"type": "WEIGHTED",
15
"workers_per_input": 1,
16
"weights": {
17
"{{user_id1}}": 1,
18
"{{user_id2}}": 1,
19
"{{user_id3}}": 1
20
}
21
}
22
},
23
"concept_ids": [
24
"{{concept_id}}"
25
],
26
"input_source": {
27
"type": "ALL_INPUTS"
28
},
29
"sample_ms": 1000,
30
"review": {
31
"strategy": "CONSENSUS",
32
"consensus_strategy_info": {
33
"approval_threshold": 2
34
},
35
"user_ids": [
36
"{{user_id4}}"
37
]
38
}
39
}
40
]
41
}'\
42
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"tasks": [
7
{
8
"type": "CONCEPTS_CLASSIFICATION",
9
"name": "Annotate {{concept_id}}",
10
"worker": {
11
"strategy": "PARTITIONED",
12
"user_ids": ["{{user_id1}}", "{{user_id2}}", "{{user_id3}}"],
13
"partitioned_strategy_info": {
14
"type": "WEIGHTED",
15
"workers_per_input": 1,
16
"weights": {
17
"{{user_id1}}": 1,
18
"{{user_id2}}": 1,
19
"{{user_id3}}": 1
20
}
21
}
22
},
23
"concept_ids": [
24
"{{concept_id}}"
25
],
26
"input_source": {
27
"type": "ALL_INPUTS"
28
},
29
"sample_ms": 1000,
30
"review": {
31
"strategy": "CONSENSUS",
32
"consensus_strategy_info": {
33
"approval_threshold": 2
34
},
35
"user_ids": [
36
"{{user_id4}}"
37
]
38
}
39
}
40
]
41
});
42
43
const requestOptions = {
44
method: 'POST',
45
headers: {
46
'Accept': 'application/json',
47
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
48
},
49
body: raw
50
};
51
52
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
53
.then(response => response.text())
54
.then(result => console.log(result))
55
.catch(error => console.log('error', error));
Copied!
Get
Get Task by ID
You can get a singular task by its ID. The ID was automatically generated when it was created.
cURL
Javascript (REST)
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/tasks/{task_id}
Copied!
1
const appId = '{YOUR_APP_ID}'
2
const taskId = '{TASK_ID}'
3
4
const requestOptions = {
5
method: 'GET',
6
headers: {
7
'Accept': 'application/json',
8
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
9
}
10
};
11
12
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/tasks/${taskId}`, requestOptions)
13
.then(response => response.text())
14
.then(result => console.log(result))
15
.catch(error => console.log('error', error));
Copied!
List All Tasks
cURL
Javascript (REST)
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/tasks
Copied!
1
const requestOptions = {
2
method: 'GET',
3
headers: {
4
'Accept': 'application/json',
5
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
6
}
7
};
8
9
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/tasks`, requestOptions)
10
.then(response => response.text())
11
.then(result => console.log(result))
12
.catch(error => console.log('error', error));
Copied!
List Tasks Assigned to User
Get only the tasks assigned to a specific user for work.
cURL
Javascript (REST)
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/tasks?worker_user_ids={{user_id}}
Copied!
1
const appId = '{YOUR_APP_ID}'
2
const workedUserId = '{WORKER_USER_ID}'
3
4
const requestOptions = {
5
method: 'GET',
6
headers: {
7
'Accept': 'application/json',
8
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
9
}
10
};
11
12
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/tasks?worker_user_ids=${workerUserId}`, requestOptions)
13
.then(response => response.text())
14
.then(result => console.log(result))
15
.catch(error => console.log('error', error));
Copied!
List Tasks Assigned to User for Review
Get only the tasks assigned to a specific user for review.
cURL
Javascript (REST)
1
curl -X GET \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
https://api.clarifai.com/v2/tasks?review_user_ids={{user_id}}
Copied!
1
const appId = '{YOUR_APP_ID}'
2
const userId = '{USER_ID}'
3
4
const requestOptions = {
5
method: 'GET',
6
headers: {
7
'Accept': 'application/json',
8
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
9
}
10
};
11
12
fetch(`https://api.clarifai.com/v2/users/me/apps/${appId}/tasks?review_user_ids=${userId}`, requestOptions)
13
.then(response => response.text())
14
.then(result => console.log(result))
15
.catch(error => console.log('error', error));
Copied!
Update
Currently, we only support updating a task by providing all information at once.
Update Task
cURL
Javascript (REST)
1
curl -X PATCH \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"action": "overwrite",
7
"tasks": [
8
{
9
"id": "{{task_id}}",
10
"type": "CONCEPTS_CLASSIFICATION",
11
"name": "Annotate {{concept_id}}",
12
"worker": {
13
"strategy": "PARTITIONED",
14
"user_ids": ["{{user_id1}}", "{{user_id2}}"],
15
"partitioned_strategy_info": {
16
"type": "WEIGHTED",
17
"workers_per_input": 1,
18
"weights": {
19
"{{user_id1}}": 1,
20
"{{user_id2}}": 1
21
}
22
}
23
},
24
"concept_ids": [
25
"{{concept_id}}"
26
],
27
"input_source": {
28
"type": "ALL_INPUTS"
29
},
30
"sample_ms": 1000,
31
"review": {
32
"strategy": "CONSENSUS",
33
"consensus_strategy_info": {
34
"approval_threshold": 2
35
},
36
"user_ids": [
37
"{{user_id3}}"
38
]
39
},
40
"status": {
41
"code": "TASK_DONE"
42
}
43
}
44
]
45
}'\
46
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"action": "overwrite",
7
"tasks": [
8
{
9
"id": "{{task_id}}",
10
"type": "CONCEPTS_CLASSIFICATION",
11
"name": "Annotate {{concept_id}}",
12
"worker": {
13
"strategy": "PARTITIONED",
14
"user_ids": ["{{user_id1}}", "{{user_id2}}"],
15
"partitioned_strategy_info": {
16
"type": "WEIGHTED",
17
"workers_per_input": 1,
18
"weights": {
19
"{{user_id1}}": 1,
20
"{{user_id2}}": 1
21
}
22
}
23
},
24
"concept_ids": [
25
"{{concept_id}}"
26
],
27
"input_source": {
28
"type": "ALL_INPUTS"
29
},
30
"sample_ms": 1000,
31
"review": {
32
"strategy": "CONSENSUS",
33
"consensus_strategy_info": {
34
"approval_threshold": 2
35
},
36
"user_ids": [
37
"{{user_id3}}"
38
]
39
},
40
"status": {
41
"code": "TASK_DONE"
42
}
43
}
44
]
45
});
46
47
const requestOptions = {
48
method: 'PATCH',
49
headers: {
50
'Accept': 'application/json',
51
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
52
},
53
body: raw
54
};
55
56
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
57
.then(response => response.text())
58
.then(result => console.log(result))
59
.catch(error => console.log('error', error));
Copied!
Delete
Delete Multiple Tasks
You can delete tasks using their IDs.
cURL
Javascript (REST)
1
curl -X DELETE \
2
-H "Authorization: Key YOUR_API_KEY" \
3
-H "Content-Type: application/json" \
4
-d '
5
{
6
"ids":["{{task_id}}"]
7
}'\
8
https://api.clarifai.com/v2/tasks
Copied!
1
const raw = JSON.stringify({
2
"user_app_id": {
3
"user_id": "{YOUR_USER_ID}",
4
"app_id": "{YOUR_APP_ID}"
5
},
6
"ids":["{{task_id}}"]
7
});
8
9
const requestOptions = {
10
method: 'DELETE',
11
headers: {
12
'Accept': 'application/json',
13
'Authorization': 'Key {YOUR_PERSONAL_TOKEN}'
14
},
15
body: raw
16
};
17
18
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
19
.then(response => response.text())
20
.then(result => console.log(result))
21
.catch(error => console.log('error', error));
Copied!
Last modified 48m ago