Tasks
Group your labeling work into tasks that can be delegated
Tasks are a powerful tool that 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)
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate CONCEPT_ID_HERE",
"worker": {
"strategy": "FULL"
},
"concept_ids": [
"CONCEPT_ID_HERE"
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "NONE"
}
}
]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and concept ID.
// Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change this to create your own non-assigned task
const CONCEPT_ID = "water";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate " + CONCEPT_ID,
"worker": {
"strategy": "FULL"
},
"concept_ids": [
CONCEPT_ID
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "NONE"
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
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)
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate CONCEPT_ID_HERE",
"worker": {
"strategy": "FULL",
"users": [
{"id": "WORKER_USER_ID_HERE"}
]
},
"concept_ids": [
"CONCEPT_ID_HERE"
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "MANUAL",
"manual_strategy_info": {
"sample_percentage": 0.5
},
"users": [
{"id": "REVIEWER_USER_ID_HERE"}
]
}
}
]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and details for
// assigning a task. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to assign your own task
const CONCEPT_ID = "water";
const WORKER_USER_ID = "WORKER_USER_ID_HERE";
const REVIEWER_USER_ID = "REVIEWER_USER_ID_HERE";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate " + CONCEPT_ID,
"worker": {
"strategy": "FULL",
"users": [
{"id": WORKER_USER_ID}
]
},
"concept_ids": [
CONCEPT_ID
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "MANUAL",
"manual_strategy_info": {
"sample_percentage": 0.5
},
"users": [
{"id": REVIEWER_USER_ID}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
Task With Partitioned Worker Strategy
The previous tasks were created with full worker strategy.
{
"strategy": "FULL"
}
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_id_1
: the first worker will get 90% of inputsweights.user_id_2
: the second worker will get 10% of inputs
- cURL
- JavaScript (REST)
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate CONCEPT_ID_HERE",
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": "USER_ID_1_HERE"},
{"id": "USER_ID_2_HERE"}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
"USER_ID_1_HERE": 90,
"USER_ID_2_HERE": 10
}
}
},
"concept_ids": [
"CONCEPT_ID_HERE"
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "NONE"
}
}
]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and details for
// creating a task. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to create your own task with partitioned worker strategy
const CONCEPT_ID = "water";
const USER_ID_1 = "USER_ID_1_HERE";
const USER_ID_2 = "USER_ID_2_HERE";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate " + CONCEPT_ID,
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": USER_ID_1},
{"id": USER_ID_2}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
USER_ID_1: 90,
USER_ID_2: 10
}
}
},
"concept_ids": [
CONCEPT_ID
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "NONE"
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
- 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.
{
"strategy": "MANUAL"
}
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)
curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate CONCEPT_ID_HERE",
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": "USER_ID_1_HERE"},
{"id": "USER_ID_2_HERE"},
{"id": "USER_ID_3_HERE"}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
"USER_ID_1_HERE": 1,
"USER_ID_2_HERE": 1,
"USER_ID_3_HERE": 1
}
}
},
"concept_ids": [
"CONCEPT_ID_HERE"
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "CONSENSUS",
"consensus_strategy_info": {
"approval_threshold": 2
},
"users": [
{"id": "USER_ID_4_HERE"}
]
}
}
]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and details for
// creating a task. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to create your own task with consensus review
const CONCEPT_ID = "water";
const USER_ID_1 = "USER_ID_1_HERE";
const USER_ID_2 = "USER_ID_2_HERE";
const USER_ID_3 = "USER_ID_3_HERE";
const USER_ID_4 = "USER_ID_4_HERE";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"tasks": [
{
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate " + CONCEPT_ID,
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": USER_ID_1},
{"id": USER_ID_2},
{"id": USER_ID_3}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
USER_ID_1: 1,
USER_ID_2: 1,
USER_ID_3: 1
}
}
},
"concept_ids": [
CONCEPT_ID
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "CONSENSUS",
"consensus_strategy_info": {
"approval_threshold": 2
},
"users": [
{"id": USER_ID_4}
]
}
}
]
});
const requestOptions = {
method: 'POST',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
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)
curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks/TASK_ID_HERE" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and task ID.
// Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change this to get a task by its ID
const TASK_ID = '77f156b3616f40c887c765f4ccb45c87';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const requestOptions = {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
}
};
fetch(`https://api.clarifai.com/v2/users/${USER_ID}/apps/${APP_ID}/tasks/${TASK_ID}`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
List All Tasks
You can get a list of tasks within your app with a GET
call. This call supports pagination.
- cURL
- JavaScript (REST)
curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////
// In this section, we set the user authentication and app ID.
// Change these strings to run your own example.
///////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const requestOptions = {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
}
};
fetch(`https://api.clarifai.com/v2/users/${USER_ID}/apps/${APP_ID}/tasks`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
List Tasks Assigned to User
Get only the tasks assigned to a specific user for work.
- cURL
- JavaScript (REST)
curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks?worker_user_ids=WORKER_USER_ID_HERE" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// worker user ID. Change these strings to run your own example.
///////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
const WORKER_USER_ID = 'WORKER_USER_ID_HERE';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const requestOptions = {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
}
};
fetch(`https://api.clarifai.com/v2/users/${USER_ID}/apps/${APP_ID}/tasks?worker_user_ids=${WORKER_USER_ID}`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
List Tasks Assigned to User for Review
Get only the tasks assigned to a specific user for review.
- cURL
- JavaScript (REST)
curl -X GET "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks?review_user_ids=REVIEW_USER_ID_HERE" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and
// review user ID. Change these strings to run your own example
///////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
const REVIEW_USER_ID = 'REVIEW_USER_ID_HERE';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const requestOptions = {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
}
};
fetch(`https://api.clarifai.com/v2/users/${USER_ID}/apps/${APP_ID}/tasks?review_user_ids=${REVIEW_USER_ID}`, requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
Update
Currently, we only support updating a task by providing all information at once.
Update Task
- cURL
- JavaScript (REST)
curl -X PATCH "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"action": "overwrite",
"tasks": [
{
"id": "TASK_ID_HERE",
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate CONCEPT_ID_HERE",
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": "USER_ID_1_HERE"},
{"id": "USER_ID_2_HERE"}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
"USER_ID_1_HERE": 1,
"USER_ID_2_HERE": 1
}
}
},
"concept_ids": [
"CONCEPT_ID_HERE"
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "CONSENSUS",
"consensus_strategy_info": {
"approval_threshold": 2
},
"users": [
{"id": "USER_ID_3_HERE"}
]
},
"status": {
"code": "TASK_DONE"
}
}
]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and details for
// updating a task. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to update your own task
const TASK_ID = '66262884195c427595d4bca033b2114e';
const CONCEPT_ID = "water";
const USER_ID_1 = "USER_ID_1_HERE";
const USER_ID_2 = "USER_ID_2_HERE";
const USER_ID_3 = "USER_ID_3_HERE";
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"action": "overwrite",
"tasks": [
{
"id": TASK_ID,
"type": "CONCEPTS_CLASSIFICATION",
"name": "Annotate " + CONCEPT_ID,
"worker": {
"strategy": "PARTITIONED",
"users": [
{"id": USER_ID_1},
{"id": USER_ID_2}
],
"partitioned_strategy_info": {
"type": "WEIGHTED",
"workers_per_input": 1,
"weights": {
USER_ID_1: 1,
USER_ID_2: 1
}
}
},
"concept_ids": [
CONCEPT_ID
],
"input_source": {
"type": "ALL_INPUTS"
},
"sample_ms": 1000,
"review": {
"strategy": "CONSENSUS",
"consensus_strategy_info": {
"approval_threshold": 2
},
"users": [
{"id": USER_ID_3}
]
},
"status": {
"code": "TASK_DONE"
}
}
]
});
const requestOptions = {
method: 'PATCH',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>
Delete
Delete Multiple Tasks
You can delete tasks using their IDs.
- cURL
- JavaScript (REST)
curl -X DELETE "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/tasks" \
-H "Authorization: Key YOUR_PAT_HERE" \
-H "Content-Type: application/json" \
-d '{
"ids":["TASK_ID_HERE"]
}'
<!--index.html file-->
<script>
///////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and task ID.
// Change these strings to run your own example.
///////////////////////////////////////////////////////////////////////////
const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change this to delete your own task
const TASK_ID = '66262884195c427595d4bca033b2114e';
///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////
const raw = JSON.stringify({
"user_app_id": {
"user_id": USER_ID,
"app_id": APP_ID
},
"ids": [TASK_ID]
});
const requestOptions = {
method: 'DELETE',
headers: {
'Accept': 'application/json',
'Authorization': 'Key ' + PAT
},
body: raw
};
fetch("https://api.clarifai.com/v2/tasks", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
</script>