> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/tasks-2/task-executions.md).

# 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"
  }
}
```