# 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](/sdk/sdk-documentation.md#project-ids) or retrieve it using the [`list_projects`](/sdk/sdk-documentation/project-level-sdk-functions/list_projects.md) function.
* **page:** integer, *default 1*
  * The page number used for paginated task retrieval.
  * Example: `1`
* **limit:** integer, *default 10*
  * The maximum number of tasks returned per request.
  * Example: `1000` 
* **status:** string, *default None*, {None, "TODO", "Completed"}
  * Filter tasks by workflow completion 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_project(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 associated with the specified batches.
  * 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_by=StringFilter(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(ne="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)`

{% 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))`

{% 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["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](/sdk/sdk-documentation/project-level-sdk-functions/get_task.md), [get\_task\_history](/sdk/sdk-documentation/project-level-sdk-functions/get_task_history.md)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.imerit.net/sdk/sdk-documentation/project-level-sdk-functions/get_tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.