> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Task object

> A task is work Lumos assigns to a user or group. This page covers which tasks you can see, how to filter the list, and how to move a task to its next status.

A task is work Lumos assigns to a user or group, such as approving an access request, creating or
removing an account by hand, or handling an error. Each task links to what it's about through
`app`, `target_user`, `access_request_id`, and `entitlement_id`. Each task also has a `status` that
changes as people act on it.

```json The Task object theme={null}
{
  "id": "5c1d2e3f-4a5b-4c7d-8e9f-0a1b2c3d4e5f",
  "type": "access-request-approval",
  "category": "approval",
  "status": "pending",
  "description": "Review Jane Doe's request for access to GitHub.",
  "instructions": null,
  "product_area": "appstore",
  "app": { "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890" },
  "target_user": {
    "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "email": "jane.doe@acme.com",
    "given_name": "Jane",
    "family_name": "Doe",
    "status": "active"
  },
  "resolved_by": null,
  "created_at": "2026-09-01T17:02:11.482913Z",
  "updated_at": "2026-09-01T17:02:11.482913Z",
  "access_request_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "entitlement_id": null
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the task. Always present. |
| `type` | string | What kind of task this is: `access-request-approval`, `manager-approval`, `account-creation`, `manual-provisioning`, `fallback-provisioning`, `account-removal`, `account-deprovisioning`, `account-modification`, `manual-deprovisioning`, `offboarding-account-removal`, `reassign-resource-owner`, `remediation`, or `error`. Always present. |
| `category` | string | The broader group `type` belongs to: `approval`, `manager-approval`, `provisioning`, `deprovisioning`, `ownership`, `remediation`, or `error`. Always present. |
| `status` | string | Where the task stands: `pending`, `accepted`, `blocked`, `staged`, `completed`, `dismissed`, `retried`, or `expired`. See [Statuses](#statuses). Always present. |
| `description` | string or null | A description of the task. |
| `instructions` | string or null | Instructions for completing the task. |
| `product_area` | string or null | The part of Lumos the task comes from: `appstore`, `access-reviews`, `onboarding`, `offboarding`, `mover`, `attribute-sync`, `platform`, or `savings`. |
| `app` | object or null | The [app](https://docs.lumos.com/reference/v1/objects/app.md) the task is about, as `{ "id": … }`. |
| `target_user` | object or null | The identity the task is about, as a [user](https://docs.lumos.com/reference/v1/objects/user.md) object. |
| `resolved_by` | object or null | The user who resolved the task. |
| `created_at` | string | When Lumos created the task. Always present. |
| `updated_at` | string | When the task last changed. Always present. |
| `access_request_id` | string or null | The [access request](https://docs.lumos.com/reference/v1/objects/access-request.md) the task belongs to, if any. |
| `entitlement_id` | string or null | The entitlement the task grants or removes. See [Entitlement IDs on tasks](#entitlement-ids-on-tasks). |
| `assignees` | array | The users and groups the task is assigned to. Only present with `expand=assignees`. A user assigned through a custom attribute, such as a manager field, is listed as the user the attribute names now. |
| `actions` | array | What you can do to the task, and the statuses each action leads to. Only present with `expand=actions`. |
| `comments` | array | Comments on the task. Only present with `expand=comments`, which only [Get Task](https://docs.lumos.com/api-reference/v1/tasks/get-task.md) accepts. |

Every field above except `assignees`, `actions`, and `comments` is always present, with `null` when
it has no value.

## Statuses

| Status | Meaning |
| - | - |
| `pending` | Created and waiting for someone to act on it. |
| `accepted` | Someone is working on it. |
| `blocked` | It can't be resolved as assigned, for example because the group it's assigned to has no members. |
| `staged` | Lumos doesn't currently put tasks in this status. |
| `completed` | Someone did what it asked. |
| `dismissed` | Closed without doing it. |
| `retried` | An error task whose failed step was retried. |
| `expired` | It expired before anyone acted on it. |

`pending`, `accepted`, and `blocked` are the open statuses. `completed`, `dismissed`, `retried`,
and `expired` are final.

## Which tasks you can see

What you can do with a task depends on how it's assigned to you and on your role. A token acts as
its user, so the same rules apply to API tokens. The table covers
[List Tasks](https://docs.lumos.com/api-reference/v1/tasks/list-tasks.md), [Get Task](https://docs.lumos.com/api-reference/v1/tasks/get-task.md),
[List Task Actions](https://docs.lumos.com/api-reference/v1/tasks/list-task-actions.md), and the endpoints that act on a
task.

| You are | List Tasks shows | Get Task and List Task Actions | Acting on the task |
| - | - | - | - |
| Assigned directly or through a group | The task | Works | Works |
| Assigned through a custom attribute, such as a manager field | The task | Works | Works |
| An App Admin who isn't assigned | Tasks on the apps they administer | `403` | Not allowed |
| An Admin | Every task, with `show_all_tasks=true` | Works | Works, including on approval tasks they aren't assigned to, through `override-approve-access-request` and `override-deny-access-request` |
| A Read Only Admin or AppStore Read Only Admin | Every task, with `show_all_tasks=true` | Works | Only on tasks they're assigned to |
| A custom role that can view every task | Every task, with `show_all_tasks=true` | Works | Only on tasks they're assigned to |

`show_all_tasks=true` returns `403` for anyone the table doesn't list with it. Acting on a task you
aren't assigned to requires the built-in Admin role.

## Filtering the list

| Parameter | Effect |
| - | - |
| `status` | One status. Without it, the list returns only open tasks: `pending`, `accepted`, and `blocked`. |
| `type` | One task type. |
| `category` | One category. Ignored when `type` is set. |
| `product_area` | One product area. |
| `search` | A search string. |
| `assigned_user_ids` | Tasks assigned to these users, directly, through a group, or through a custom attribute. An unknown ID returns `404`. |
| `assigned_group_ids` | Tasks assigned to these [groups](https://docs.lumos.com/reference/v1/objects/group.md). An unknown ID returns `404`. |
| `access_request_id` | Tasks on one access request. An unknown ID returns `404`. |
| `show_all_tasks` | Every task in your organization, for the roles above. |
| `order_by` | `created_at`, `type`, `app`, or `target_user`, optionally followed by ` desc`. Newest first by default. |

An unknown value for `status`, `type`, `category`, or `product_area` returns `400`. An `order_by`
value outside the list above also returns `400`. One unknown ID in `assigned_user_ids` or
`assigned_group_ids` returns `404` with `code` `not_found`, even when the other IDs match.

The maximum `page_size` on this endpoint is 100. [List Tasks](https://docs.lumos.com/api-reference/v1/tasks/list-tasks.md)
reduces a larger value to 100.

## Acting on a task

Four endpoints act on a task, and a fifth adds a comment. The four return `204` when they succeed.

**Complete or dismiss.** [Complete Task](https://docs.lumos.com/api-reference/v1/tasks/complete-task.md) and
[Dismiss Task](https://docs.lumos.com/api-reference/v1/tasks/dismiss-task.md) run the one action that moves the task to
`completed` or `dismissed`. When there isn't exactly one such action:

* If no action moves the task to that status, the call returns `400` with `code`
  `task.no_action_for_status`.
* If such an action exists but you can't take it, the call returns `403`.
* If you can take more than one, the call returns `400` with `code` `task.action_ambiguous`. Use
  [Perform Task Action](https://docs.lumos.com/api-reference/v1/tasks/perform-task-action.md) to choose one.
* If the task is already completed or dismissed, the call returns `400` with `code`
  `task.no_action_for_status`, because no action moves a finished task.

**Perform a specific action.** Call [List Task Actions](https://docs.lumos.com/api-reference/v1/tasks/list-task-actions.md)
first, or list tasks with `expand=actions`. Each item has an `action_type` and the `transitions` it
can make. An assignee of a pending task of type `access-request-approval` sees something like this:

```json theme={null}
[
  { "action_type": "reassign-access-request", "transitions": [{ "transition_to": null }] },
  { "action_type": "approve-access-request", "transitions": [{ "transition_to": "completed" }] },
  { "action_type": "deny-access-request", "transitions": [{ "transition_to": "dismissed" }] }
]
```

A `transition_to` of `null` means the action leaves the status as it is.

Send the `action_type` to [Perform Task Action](https://docs.lumos.com/api-reference/v1/tasks/perform-task-action.md). Add
`transition_to` to choose the resulting status. It must be one of that action's transitions.
Otherwise the call returns `400` with `code` `task.transition_not_allowed`. When the action has one
transition, omit `transition_to`, and Lumos uses that transition. An `action_type` that Lumos
doesn't recognize returns `400` with `code` `task.action_unknown`.

**Reassign.** [Reassign Task](https://docs.lumos.com/api-reference/v1/tasks/reassign-task.md) replaces the task's assignees
with the `user_ids` and `group_ids` you send. Send `"replace": false` to add them to the existing
assignees instead.

* Reassign Task skips IDs that don't match a user or group. If none match, the call returns `400`.
* Replacing also removes assignments made through a custom attribute, such as a manager field.
  `assignees` lists such an assignment as a user, so sending that list back assigns that user
  directly, and the task stops following the attribute.
* For some task types, reassigning also changes the status. A `blocked` task of type
  `account-removal` returns to `pending`.

**Comment.** [Create Task Comment](https://docs.lumos.com/api-reference/v1/tasks/create-task-comment.md) adds a comment of
1 to 4,000 characters and returns it with `201`.

The four endpoints that act on a task return `409` with `code` `task.already_in_status` when the
task is already in the status the action would move it to. Any of the five endpoints returns `403`
when you aren't allowed to take the action.

## Entitlement IDs on tasks

`entitlement_id` is the `id` of the [entitlement](https://docs.lumos.com/reference/v1/objects/entitlement.md) the task grants
or removes. Pass it to [Get Entitlement](https://docs.lumos.com/api-reference/v1/entitlements/get-entitlement.md). It's
`null` when the task isn't about one entitlement. Approval tasks always carry `null`. If you're
moving from requestable permissions, see
[Migrate requestable permissions to entitlements](https://docs.lumos.com/reference/v1/migrate/permissions-to-entitlements.md).

## Endpoints

| Endpoint | Path |
| - | - |
| [List Tasks](https://docs.lumos.com/api-reference/v1/tasks/list-tasks.md) | `GET /v1/tasks` |
| [Get Task](https://docs.lumos.com/api-reference/v1/tasks/get-task.md) | `GET /v1/tasks/{task_id}` |
| [List Task Actions](https://docs.lumos.com/api-reference/v1/tasks/list-task-actions.md) | `GET /v1/tasks/{task_id}/actions` |
| [Complete Task](https://docs.lumos.com/api-reference/v1/tasks/complete-task.md) | `POST /v1/tasks/{task_id}:complete` |
| [Dismiss Task](https://docs.lumos.com/api-reference/v1/tasks/dismiss-task.md) | `POST /v1/tasks/{task_id}:dismiss` |
| [Perform Task Action](https://docs.lumos.com/api-reference/v1/tasks/perform-task-action.md) | `POST /v1/tasks/{task_id}:perform-action` |
| [Reassign Task](https://docs.lumos.com/api-reference/v1/tasks/reassign-task.md) | `POST /v1/tasks/{task_id}:reassign` |
| [Create Task Comment](https://docs.lumos.com/api-reference/v1/tasks/create-task-comment.md) | `POST /v1/tasks/{task_id}/comments` |