# get\_tasks

`imerit_ango.sdk.SDK.`

## get\_tasks(project\_id, page, limit, status, stage, batches, include\_answer, task\_filter, sort, fields)

Retrieve tasks from your project.

### Parameters

* **project\_id:** string
  * The unique identifier for the project. You can find the project ID in [the user interface](https://docs.imerit.net/sdk/sdk-documentation/..#project-ids) or retrieve it using the [`list_projects`](https://docs.imerit.net/sdk/sdk-documentation/project-level-sdk-functions/list_projects) function.
* **page:** integer, *default 1*
  * Current page.
  * Example: `1`
* **limit:** integer, *default 10*
  * Page size. Default 10, maximum 1000.
  * Example: `100`
* **status:** string, *default None*, {None, "TODO", "Completed"}
  * Filter tasks by status.
  * Example: `'Completed'`
* **stage:** string, *default None*
  * Pass a stage ID to filter tasks by stage. You can obtain a stage's ID by running `get_export(project_id)`on the project where you'd like to get the stage IDs.
  * Example: `'Label'` or `"1a1a2d88-ddad-457a-aac8-fe50a3a65272"`
* **batches**: list\[str], *default None*
  * Filter tasks by batch (e.g., only get tasks belonging to the batch specified)
  * Example: `['batch_1', 'batch_2']`
* **include\_answer:** bool, *default False*
  * If set to True, the response will contain the "answer" field which contains the annotations for each task.
* **task\_filter:** TaskFilter, *Optional*
  * Applies advanced filtering rules to narrow down the returned tasks.
  * Example: `TaskFilter(stage=["Completed"])` 
  * More information about the TaskFilter class is available [here](#taskfilter).
* **sort:** string, *Optional*
  * Specifies the ordering of the returned tasks based on a given rule.
  * Sort tasks in ascending order by specifying the field name directly (e.g., `"externalId"`), or in descending order by prefixing the field name with a minus sign (e.g., `"-externalId"`).
  * Multiple sorting criteria can be combined using commas and are applied sequentially in the order they are specified. (e.g., `"-priority, -createdAt"`)
  * Example: `"-externalId"`
* **fields:** string, *Optional*
  * Limits the response to only the specified task fields.
  * Example: `"externalId,createdBy,createdAt"`

***

#### **TaskFilter**

Defines a structured and expressive way to filter tasks.

```python
from imerit_ango.models.task_filter import TaskFilter
```

* **stage:** List\[str] or StringFilter
  * Filters tasks by workflow stage.
  * Examples: 
    * `TaskFilter(stage=["stage_id_1", "stage_id_2"])` 
    * `TaskFilter(stage=[StringFilter(eq="stage_id_1")]`
* **batches:** List\[str] or StringFilter
  * Filters tasks by batch identifiers.
  * Examples:
    * `TaskFilter(batches=["batch_id_1", "batch_id_2"])` 
    * `TaskFilter(batches=[StringFilter(eq="batch_id_1")]`
* **status:** TaskStatus, string, StringFilter
  * Filters tasks by status of tasks.
* **review\_status:** ReviewStatus, string, StringFilter
  * Filters tasks by review outcome.
* **task\_type:** TaskType, string, StringFilter
  * Filters tasks by type. 
* **assignee:** string or StringFilter
  * Filters tasks by assignee.
  * Examples:
    * `TaskFilter(assignee="labeler_1@imerit.net")`
    * `TaskFilter(assignee=StringFilter(in_list=["labeler_1@imerit.net", "labeler_2@imerit.net"]))`
* **external\_id:** string or StringFilter
  * Filters tasks by external ID.
  * Examples:
    * `TaskFilter(external_id="image-1.png")`
    * `TaskFilter(external_id=StringFilter(in_list=["image-1.png", "image-2.png"]))`
* **created\_at:** DateRange
  * Filters tasks based on creation timestamp.
  * Example:
    * `TaskFilter(created_at=DateRange(gte=datetime(2024, 1, 1)))`
* **updated\_at:** DateRange
  * Filters tasks based on last update timestamp.
  * Example:
    * `TaskFilter(updated_at=DateRange(lte=datetime(2025, 12, 31)))`
* **created\_by:** string or StringFilter
  * Filters tasks by the user who created them.
  * Examples:
    * `TaskFilter(created_by="labeler_1@imerit.net")`
    * `TaskFilter(created_by=StringFilter(eq="labeler_1@imerit.net"))`
* **updated\_by:** string or StringFilter
  * Filters tasks by the user who last updated them.
  * Examples:
    * `TaskFilter(updated_by="labeler_1@imerit.net")`
    * `TaskFilter(updated_byStringFilter(eq="labeler_1@imerit.net"))`
* **priority:** int or NumberRange
  * Filters tasks by priority level.
  * Examples:
    * `TaskFilter(priority=100)`
    * `TaskFilter(priority=NumberRange(gte=10))`
* **duration:** NumberRange
  * Filters tasks by the duration of the current stage (in seconds).
  * Example: `TaskFilter(duration=NumberRange(gte=3600))`
* **total\_duration:** NumberRange
  * Filters tasks by total accumulated duration across all stages (in seconds).
  * Example: `TaskFilter(total_duration=NumberRange(lte=3600))`
* **open\_issues\_count:** int or NumberRange
  * Filters tasks by the number of open issues.
  * Examples:
    * `TaskFilter(open_issues_count=1)`
    * `TaskFilter(open_issues_count=NumberRange(gte=1))`
* **is\_draft:** bool
  * Filters tasks based on draft status.
  * Example: `TaskFilter(is_draft=True)`
* **is\_skipped:** bool
  * Filters tasks that were skipped during processing.
  * Example: `TaskFilter(is_skipped=True)`
* **is\_benchmark:** bool
  * Filters benchmark tasks.
  * Example: `TaskFilter(is_benchmark=True)`

{% tabs %}
{% tab title="StringFilter" %}

#### **StringFilter**

Defines filtering rules for string-based task fields.

<pre class="language-python" data-full-width="false"><code class="lang-python"><strong>from imerit_ango.models.task_filter import StringFilter
</strong></code></pre>

**Parameters:**

* **eq:** string, *Optional*
  * Matches tasks where the field value is exactly equal to the specified string.
  * Example: `StringFilter(eq="completed")`
* **ne:** string, *Optional*
  * Matches tasks where the field value is not equal to the specified string.
  * Example: `StringFilter(neq="draft")`
* **regex:** string, *Optional*
  * Matches tasks where the field value satisfies the given regular expression.
  * Example: `StringFilter(regex="^batch_.*")`
* **in\_list:** List\[string], *Optional*
  * Matches tasks where the field value is included in the provided list of strings.
  * Example: `StringFilter(in_list=["batch-1", "batch-2"])`
* **nin:** List\[string], *Optional*
  * Matches tasks where the field value is not included in the provided list of strings.
  * Example: `StringFilter(nin=["batch-1", "batch-2"])`
* **exists:** bool, *Optional*
  * Matches tasks based on whether the field exists or is defined.
  * Example: `StringFilter(exists=True)`&#x20;

{% hint style="info" %}
Each field is optional. You may specify one or more filters depending on your use case.
{% endhint %}
{% endtab %}

{% tab title="NumberRange" %}

#### **NumberRange**

Defines filtering rules for numeric task fields.

```python
from imerit_ango.models.task_filter import NumberRange
```

**Parameters:**

* **eq:** int or float, *Optional*
  * Matches tasks where the field value is exactly equal to the specified number.
  * Example: `NumberRange(eq=10)`
* **ne:** int or float, *Optional*
  * Matches tasks where the field value is not equal to the specified number.
  * Example: `NumberRange(ne=0)`
* **gt:** int or float, *Optional*
  * Matches tasks where the field value is greater than the specified number.
  * Example: `NumberRange(gt=5)`
* **gte:** int or float, *Optional*
  * Matches tasks where the field value is greater than or equal to the specified number.
  * Example: `NumberRange(gte=100)`
* **lt:** int or float, *Optional*
  * Matches tasks where the field value is less than the specified number.
  * Example: `NumberRange(lt=3.5)`
* **lte:** int or float, *Optional*
  * Matches tasks where the field value is less than or equal to the specified number.
  * Example: `NumberRange(lte=25)`

{% hint style="info" %}
Each field is optional. You may specify one or more filters depending on your use case.
{% endhint %}
{% endtab %}

{% tab title="DateRange" %}

#### **DateRange**

Defines filtering rules for date and time–based task fields.

```python
from imerit_ango.models.task_filter import DateRange
from datetime import datetime
```

**Parameters:**

* **gt:** datetime, *Optional*
  * Matches tasks where the field value is later than the specified date and time.
  * Example: `DateRange(gt=datetime(2024, 1, 1))`
* **gte:** datetime, *Optional*
  * Matches tasks where the field value is later than or equal to the specified date and time.
  * Example: `DateRange(gte=datetime(2024, 1, 1, 12, 0))`
* **lt:** datetime, *Optional*
  * Matches tasks where the field value is earlier than the specified date and time.
  * Example: `DateRange(lt=datetime(2024, 12, 31, 23, 59, 59))`
* **lte:** datetime, *Optional*
  * Matches tasks where the field value is earlier than or equal to the specified date and time.
  * Example: `DateRange(lte=datetime(2024, 6, 30))`&#x20;

{% hint style="info" %}
Each field is optional. You may specify one or more filters depending on your use case.
{% endhint %}
{% endtab %}
{% endtabs %}

Returns:

* **output:** dict
  * A dictionary containing the result of the operation.
  * Including a `status` field indicating whether the request was successful and a `data` field containing the response payload with updated resources produced by the operation.

### Example

Retrieve the first ten tasks from the project:

{% tabs %}
{% tab title="python" %}

```python
import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_tasks(project_id=project_id, page=1, limit=10)

data_url = sdk_response['data']['tasks'][0]['asset']['data']
external_id = sdk_response['data']['tasks'][0]['asset']['externalId']
```

{% endtab %}

{% tab title="curl" %}

```bash
curl -X GET "https://imeritapi.ango.ai/v2/project/$PROJECT_ID/tasks?page=1&limit=10&includeAnswer=False" \
  -H "Content-Type: application/json" \
  -H "apikey: $ANGO_API_KEY"
```

{% endtab %}
{% endtabs %}

Retrieve all tasks from the project:

{% tabs %}
{% tab title="python" %}

```python
import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

page = 1
num_tasks = 1
task_list = []
while len(task_list) < num_tasks:
    response = ango_sdk.get_tasks(project_id=project_id, page=page, limit=50)
    tasks = response.get('data', {}).get('tasks', [])
    num_tasks = response.get('data', {}).get('total', 0)

    task_list.extend(tasks)
    page += 1

print("The number of retrieved tasks is: " + str(len(task_list)))
```

{% endtab %}
{% endtabs %}

Sort tasks by externalId and retrieve the first ten tasks from the project:

{% tabs %}
{% tab title="python" %}

```python
import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_tasks(project_id, page=1, limit=10, sort="externalId")

tasks = sdk_response.get["data"]["tasks"]
for task in tasks:
    print(task.get("externalId"))
```

{% endtab %}
{% endtabs %}

Filter the retrieved tasks:

{% tabs %}
{% tab title="python" %}

```python
import os
from datetime import datetime
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.task_filter import TaskFilter, StringFilter, NumberRange, DateRange

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

task_filter = TaskFilter(
    assignee=StringFilter(eq="labeler_1@imerit.net"),
    updated_at=DateRange(lte=datetime.now(), gte=datetime(2024, 1, 1)),
    duration=NumberRange(lte=3600),
    is_skipped=False,
)

sdk_response = ango_sdk.get_tasks(project_id, page=1, limit=10, task_filter=task_filter)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**See also**

[get\_task](https://docs.imerit.net/sdk/sdk-documentation/project-level-sdk-functions/get_task), [get\_task\_history](https://docs.imerit.net/sdk/sdk-documentation/project-level-sdk-functions/get_task_history)
{% endhint %}