# TaskExecutions

## Introduction

`TaskExecutions` represent concrete task instances for users or departments.

Executions are usually created from [TaskAssignments](/api-reference/tasks-2/task-assignments.md) and [TaskTemplates](/api-reference/tasks-2/task-templates.md).

## Model Definition

**Alias**

`taskExecution`

**Relations**

| Relation                                                             | Key                  | Type       | Relation Field(s)              |
| -------------------------------------------------------------------- | -------------------- | ---------- | ------------------------------ |
| [TaskProgressFields](/api-reference/tasks-2/task-progress-fields.md) | `taskProgressFields` | Has many   | `task_progress_fields.task_id` |
| [TaskAssignment](/api-reference/tasks-2/task-assignments.md)         | `taskAssignment`     | Belongs to | `task_assignment_id`           |
| [TaskTemplate](/api-reference/tasks-2/task-templates.md)             | `taskTemplate`       | Belongs to | `task_template_id`             |
| `TaskStatus`                                                         | `taskStatus`         | Has one    | `tasks_status_id`              |
| [User](/api-reference/users.md)                                      | `lastActivityUser`   | Belongs to | `last_activity_user_id`        |
| [TaskExecution](/api-reference/tasks-2/task-executions.md)           | `parent`             | Belongs to | `parent_id`                    |
| [TaskExecutions](/api-reference/tasks-2/task-executions.md)          | `children`           | Has many   | `parent_id`                    |

## Task status indicators

Possible values for `task_status_id`:

* `open`
* `in_progress`
* `in_progress_delayed`
* `done`
* `done_delayed`
* `denied`
* `missed`

## List by date range

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions`

**Request Keys**

| Key            | Type     | Default | Description          |
| -------------- | -------- | ------- | -------------------- |
| `period_start` | datetime | -       | Start of date range. |
| `period_end`   | datetime | -       | End of date range.   |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions?period_start=2026-05-11+00:00:00&period_end=2026-05-11+23:59:59', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
[
  {
    "id": 812,
    "task_assignment_id": 558,
    "task_template_id": 203,
    "task_status_id": "open",
    "for_execution_date": "2026-05-11 09:00:00",
    "achieved_points": 0,
    "max_points": 0
  }
]
```

## List by assignment and date range

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/assignments/{taskAssignment}/executions`

**Request Keys**

| Key              | Type     | Default | Description          |
| ---------------- | -------- | ------- | -------------------- |
| `taskAssignment` | integer  | -       | TaskAssignment ID.   |
| `period_start`   | datetime | -       | Start of date range. |
| `period_end`     | datetime | -       | End of date range.   |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/assignments/558/executions?period_start=2026-05-11+00:00:00&period_end=2026-05-11+23:59:59', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
[
  {
    "id": 812,
    "task_assignment_id": 558,
    "task_template_id": 203,
    "task_status_id": "open"
  }
]
```

## Count

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions/count`

**Request Keys**

No additional request keys.

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "count": 12
}
```

## Show

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions/{taskExecution}`

**Request Keys**

| Key             | Type    | Default | Description       |
| --------------- | ------- | ------- | ----------------- |
| `taskExecution` | integer | -       | TaskExecution ID. |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/812', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "id": 812,
  "task_assignment_id": 558,
  "task_template_id": 203,
  "task_status_id": "open",
  "for_execution_date": "2026-05-11 09:00:00",
  "achieved_points": 0,
  "max_points": 0
}
```

## Create

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/executions`

**Request Keys**

| Key                    | Type     | Default | Description                                                              |
| ---------------------- | -------- | ------- | ------------------------------------------------------------------------ |
| `task_assignment_id`\* | integer  | -       | Related [TaskAssignment](/api-reference/tasks-2/task-assignments.md) ID. |
| `task_template_id`\*   | integer  | -       | Related [TaskTemplate](/api-reference/tasks-2/task-templates.md) ID.     |
| `parent_id`            | integer  | `null`  | Parent TaskExecution ID for child executions.                            |
| `task_status_id`       | string   | `open`  | Initial status ID.                                                       |
| `for_execution_date`   | datetime | `null`  | Execution date/time.                                                     |

Keys with `*` are required.

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/executions', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'task_assignment_id' => 558,
        'task_template_id' => 203
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_assignment_id": 558,
    "task_template_id": 203,
    "task_status_id": "open"
  }
}
```

## Progress

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/tasks-2/executions/{taskExecution}/progress`

**Request Keys**

| Key                                  | Type       | Default | Description                                                                    |
| ------------------------------------ | ---------- | ------- | ------------------------------------------------------------------------------ |
| `taskExecution`                      | integer    | -       | Route parameter. TaskExecution ID.                                             |
| `{field-key}`                        | field type | -       | Field value keyed by [TaskField](/api-reference/tasks-2/task-fields.md) `key`. |
| `{field-key}_additional_information` | string     | `null`  | Optional additional information for the field value.                           |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/tasks-2/executions/812/progress', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'comment' => 'Started checklist'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_status_id": "in_progress"
  }
}
```

## Finish

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/executions/{taskExecution}/progress/finish`

**Request Keys**

| Key                                  | Type       | Default | Description                                                                    |
| ------------------------------------ | ---------- | ------- | ------------------------------------------------------------------------------ |
| `taskExecution`                      | integer    | -       | Route parameter. TaskExecution ID.                                             |
| `{field-key}`                        | field type | -       | Field value keyed by [TaskField](/api-reference/tasks-2/task-fields.md) `key`. |
| `{field-key}_additional_information` | string     | `null`  | Optional additional information for the field value.                           |
| `delayed_reason`                     | string     | `null`  | Delayed reason if delayed-state completion requires it.                        |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/executions/812/progress/finish', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'comment' => 'Checklist completed'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_status_id": "done"
  }
}
```

## Deny

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/executions/{taskExecution}/deny`

**Request Keys**

| Key             | Type    | Default | Description                                                |
| --------------- | ------- | ------- | ---------------------------------------------------------- |
| `taskExecution` | integer | -       | Route parameter. TaskExecution ID.                         |
| `deny_reason`   | string  | `null`  | Deny reason (required when assignment policy requires it). |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/executions/812/deny', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'deny_reason' => 'Equipment unavailable'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_status_id": "denied",
    "deny_reason": "Equipment unavailable"
  }
}
```

## Reset

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/tasks-2/executions/{taskExecution}/reset`

**Request Keys**

| Key             | Type    | Default | Description       |
| --------------- | ------- | ------- | ----------------- |
| `taskExecution` | integer | -       | TaskExecution ID. |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/tasks-2/executions/812/reset', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_status_id": "in_progress"
  }
}
```

## Update state

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/tasks-2/executions/{taskExecution}/status`

**Request Keys**

| Key                | Type    | Default | Description                        |
| ------------------ | ------- | ------- | ---------------------------------- |
| `taskExecution`    | integer | -       | Route parameter. TaskExecution ID. |
| `task_status_id`\* | string  | -       | New task status ID.                |

Keys with `*` are required.

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/tasks-2/executions/812/status', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'task_status_id' => 'in_progress'
    ]
]);
```

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 812,
    "task_status_id": "in_progress"
  }
}
```

## List previous workflow nodes

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions/{taskAssignment}/workflow-nodes/previous`

**Request Keys**

| Key              | Type    | Default | Description                                                   |
| ---------------- | ------- | ------- | ------------------------------------------------------------- |
| `taskAssignment` | integer | -       | TaskAssignment ID used as workflow root.                      |
| `levels`         | integer | `0`     | Maximum levels to resolve (`0` resolves all previous levels). |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/558/workflow-nodes/previous?levels=2', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
[
  {
    "id": 9001,
    "type": "taskExecutionFinished",
    "level": 1,
    "dispatchable_id": 812,
    "dispatchable_type": "taskExecution"
  },
  {
    "id": 9000,
    "type": "formMessageSent",
    "level": 2,
    "dispatchable_id": 301,
    "dispatchable_type": "formMessage"
  }
]
```

## Show previous workflow node

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions/{taskAssignment}/workflow-nodes/previous/{level}`

**Request Keys**

| Key              | Type    | Default | Description                              |
| ---------------- | ------- | ------- | ---------------------------------------- |
| `taskAssignment` | integer | -       | TaskAssignment ID used as workflow root. |
| `level`          | integer | -       | Previous workflow level to return.       |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/558/workflow-nodes/previous/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "id": 9001,
  "type": "taskExecutionFinished",
  "level": 1,
  "dispatchable_id": 812,
  "dispatchable_type": "taskExecution"
}
```

## Show previous workflow node dispatchable

**Definition**

<mark style="color:green;">`GET`</mark> `/api/tasks-2/executions/{taskAssignment}/workflow-nodes/previous/{level}/dispatchable`

**Request Keys**

| Key              | Type    | Default | Description                                             |
| ---------------- | ------- | ------- | ------------------------------------------------------- |
| `taskAssignment` | integer | -       | TaskAssignment ID used as workflow root.                |
| `level`          | integer | -       | Previous workflow level whose dispatchable is returned. |
| `include`        | string  | -       | Optional result-control include parameter.              |
| `appends`        | string  | -       | Optional result-control appends parameter.              |

**Example Request**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/tasks-2/executions/558/workflow-nodes/previous/1/dispatchable?include=taskTemplate:id,title|taskAssignment:id,title&appends=visibility_start_time', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

**Example Response**

```json
{
  "id": 812,
  "task_assignment_id": 558,
  "task_template_id": 203,
  "task_status_id": "done",
  "visibility_start_time": "2026-04-29 08:45:00",
  "task_template": {
    "id": 203,
    "title": "Safety Checklist"
  },
  "task_assignment": {
    "id": 558,
    "title": "Morning Shift"
  }
}
```


---

# 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.api.intratool.de/api-reference/tasks-2/task-executions.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.