--- title: "Returns the task for the key." method: GET path: "/tasks/key/{taskIdentifier}" tags: ["tasks"] --- # Returns the task for the key. `GET /tasks/key/{taskIdentifier}` ## Request - Base URL: `https://api.awork.com/api/v1` - URL: `https://api.awork.com/api/v1/tasks/key/{taskIdentifier}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns the task for the key. The key is matched within the current workspace. The user must have permission to access the requested resource. ## Path parameters - `taskIdentifier` string, required ## Response `200` OK - TaskModel - `name` string, required: The name of the task. Max allowed length: 1000 characters. - `description` string, nullable: The description of the task. Max allowed length: 25000 characters. - `isPrio` boolean: Whether this task is marked as priority. - `startOn` string, date-time, nullable: The expected start date and time of the task. - `dueOn` string, date-time, nullable: The expected due date and time of the task. - `laneOrder` integer: The lane order defines the vertical position in the task board. - `plannedDuration` integer: The expected planned workload of the task, in seconds. - `id` string, uuid: The Id of the task. - `taskNumber` integer, nullable: The sequential task number within the project. Unique within the project, never reused even after deletion. - `taskIdentifier` string, nullable: The full task identifier combining project key and task number (e.g., "NIKE-42"). Maintained by the service layer, updated when project key changes. - `isExternal` boolean: True if the model is coming from an external workspace (awork Connect). False otherwise. - `createdVia` string, nullable: The origin of the task. From which 'flow' the task was created. Automatically set by the backend. - `isHiddenForConnectUsers` boolean: True if the task is hidden for external workspace users. False otherwise. - `baseType` 'private' | 'projecttask': The base type of the task. Can be 'private' for a private task or 'projecttask' for a project task. - `taskStatusId` string, uuid: The id of the status for this task. - `taskStatus` TaskStatus - `id` string, uuid: The primary identifier of this task status. - `name` string, nullable: The name of the task status. - `type` string, nullable: Of what general type is this task status?. - `order` number, double, nullable: The order of the task status in a project. - `icon` string, nullable: The icon of the task status. - `projectId` string, uuid, nullable: Is set if the task status is related to a project. - `projectTypeId` string, uuid, nullable: Is set if the task status is related to a project type. - `workflowId` string, uuid, nullable: Is set if the task status is related to a workflow. - `createdOn` string, date-time: The date this entity was created. - `createdBy` string, uuid: The id of the user who created this entity. - `updatedOn` string, date-time: The date this entity was last modified. - `updatedBy` string, uuid: The id of the user who last modified this entity. - `isExternal` boolean: True if the task status is coming from an external workspace (awork Connect). - `typeOfWorkId` string, uuid: The id of the type of work of this task. - `typeOfWork` NestedTaskTypeModel - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `icon` string, nullable: The icon of the type. - `isArchived` boolean: Whether the type is archived. - `assignees` NestedUserModelForTasks[], nullable: The list assigned users of this task, or empty if not user was assigned. - `id` string, uuid: The identifier of the nested model. - `firstName` string, nullable: The first name of the user. - `lastName` string, nullable: The last name of the user. - `hasImage` boolean, nullable: Whether this user has a profile image. - `plannedEffort` integer: The planned effort of the user assigned to the task, in seconds. - `isDistributedPlannedEffort` boolean: If the PlannedEffort was calculated as distributed effort. - `updatedOn` string, date-time: The date this task assignee was last modified. - `isExternal` boolean: True if the model is coming from an external workspace (awork Connect). False otherwise. - `projectId` string, uuid, nullable: The id of the project this task is assigned to. Only set if this is a project task. In this case, it is equal to the EntityId. - `project` NestedProjectModelForTasks - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `projectKey` string, nullable: The unique project key within the workspace (e.g., "NIKE"). Maximum 32 characters, uppercase letters, numbers, and dashes only. - `projectStatus` NestedStatusModel - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `description` string, nullable: The description of the type. - `type` string, nullable: The type of the status. - `isArchived` boolean: Whether the type is archived. - `company` NestedCompanyModelForTasks - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `hasImage` boolean: Whether the company has a profile image. - `description` string, nullable: The description of the company. - `companyId` string, uuid, nullable: The companyId of the project. - `projectType` NestedTypeModel - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `icon` string, nullable: The icon of the type. - `isArchived` boolean: Whether the type is archived. - `hasImage` boolean: Whether the project has an image. - `isPrivate` boolean: Whether the project is private. - `isBillableByDefault` boolean, nullable: Whether the project is billable by default. - `members` ProjectMemberModel[], nullable: The list of all members of the project. - `id` string, uuid - `userId` string, uuid - `projectRoleId` string, uuid - `projectRoleName` string, nullable - `isResponsible` boolean - `isExternal` boolean: True if the model is coming from an external workspace (awork Connect). False otherwise. - `color` string, nullable: The color of the project for display purposes in awork. Can be null when no color assigned. - `createdBy` string, uuid: The created by of the project. - `teams` NestedTeamModel[], nullable: The ids of the team the project is associated to. - `id` string, uuid - `customFields` ProjectCustomField[], nullable: Custom fields of the project. - `customFieldDefinitionId` string, uuid: The custom field definition id. - `userIdValue` string, uuid, nullable: The the user id value. - `clientIdValue` string, uuid, nullable: The client id value. - `numberValue` number, double, nullable: The number value. - `selectionOptionIdValue` string, uuid, nullable: The selection option id value. - `selectionOption` CustomFieldSelectionOption - `id` string, uuid: The id of the custom field selection option. - `value` string, required: The selection value which can be later used in a select custom field. - `color` 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'steel': The color of the selection option. - `order` number, double: The order of the custom field selection option. - `textValue` string, nullable: The text value. - `dateValue` string, date-time, nullable: The date value. - `booleanValue` boolean, nullable: The boolean value. - `isExternal` boolean: True if the model is coming from an external workspace (awork Connect). False otherwise. - `correlationId` string, uuid: The correlation id between parent and subtasks, meaning it's either the ParentId or its own Id. - `parentId` string, uuid, nullable: The id of the parent task this of this subtask. Only set if this is a subtask. - `parentTask` NestedParentTaskModel - `id` string, uuid: The identifier of the nested model. - `name` string, nullable: The name of the entity. - `createdBy` string, uuid: The id of the user who created this task. - `userId` string, uuid, nullable: The id of the user of the private task. Null for project tasks. - `assigneeIds` string[], nullable: List of assignee user ids of this task. - `isSubtask` boolean: True if the task is a subtask. - `numberOfSubtasks` integer, nullable: The number of subtasks of this task. Null if it's not a parent task. - `hasAttachment` boolean: Whether this task has an attachment. - `lists` TaskOrderList[], nullable: The lists to which the task is assigned to. - `id` string, uuid: The id of the task list. - `createdOn` string, date-time: The date this task list was created. - `createdBy` string, uuid: The id of the user who created this task list. - `updatedOn` string, date-time: The date this task list was last modified. - `updatedBy` string, uuid: The id of the user who last modified this task list. - `name` string, nullable: The name of the list. - `order` number, double, nullable: The order of the list. - `plannedDuration` integer, nullable: The planned duration for this task list, in seconds. - `totalPlannedDuration` integer, nullable: The total planned duration for this task list, including all primary tasks (parent tasks which have this tacklist as PrimaryTaskListId), in seconds. Calculated: sum PlannedDuration of primary tasks in list Archived task lists are not included in the calculation. - `totalPlannedDurationWithHierarchy` integer, nullable: The total planned duration for this task list, including all primary tasks (parent tasks which have this task list as PrimaryTaskListId), in seconds. Calculated: max(PlannedDuration, sum TotalPlannedDurationWithHierarchy of primary tasks in list) Archived task lists are not included in the calculation. - `isArchived` boolean: Whether the task list has been archived. - `isHiddenForConnectUsers` boolean: True if the task in this list will be not visible for external workspace users. False otherwise. - `orderOfTask` number, double, nullable: The order of the task in the list. - `entityId` string, uuid, nullable: The id of the entity this task is assigned to. This is the id of the project if this is a project task, or the id of a user if this is a private task. See 'BaseType' for supported types. - `userId` string, uuid, nullable: The id of the user of the private task. - `tags` TaskTagModel[], nullable: The list of tags. - `id` string, uuid - `name` string, nullable: The name of the tag. - `color` string, nullable: The color of the tag. - `createdOn` string, date-time: The date this task was created. - `createdBy` string, uuid: The id of the user who created this task. - `updatedOn` string, date-time: The date this task was last modified. - `updatedBy` string, uuid: The id of the user who last modified this task. - `closedOn` string, date-time, nullable: The date the task was set to closed. - `closedBy` string, uuid, nullable: The user who closed the task. - `order` number, double: The order of the task in a task status column. - `subtaskOrder` number, double, nullable: The order of the subtask relative to its parent task. - `createdFromTaskId` string, uuid, nullable: When the task was created by a recurrency rule, the id is the link to the template of which the task was created. - `isRecurring` boolean: If the task is a recurrency template (used to create new tasks by a recurrency rule), the flag is true. - `customFields` CustomField[], nullable: Custom fields of the task. - `customFieldDefinitionId` string, uuid: The custom field definition id. - `userIdValue` string, uuid, nullable: The the user id value. - `clientIdValue` string, uuid, nullable: The client id value. - `numberValue` number, double, nullable: The number value. - `selectionOptionIdValue` string, uuid, nullable: The selection option id value. - `selectionOption` CustomFieldSelectionOption - `id` string, uuid: The id of the custom field selection option. - `value` string, required: The selection value which can be later used in a select custom field. - `color` 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'steel': The color of the selection option. - `order` number, double: The order of the custom field selection option. - `textValue` string, nullable: The text value. - `dateValue` string, date-time, nullable: The date value. - `booleanValue` boolean, nullable: The boolean value. - `deriveDatesFromSubtasks` boolean: When true, if the task is a parent task, the StartOn and DueOn will be automatically adjusted to the start and due date of the subtasks. - `trackedDuration` integer, nullable: The summed up duration of all time trackings directly on this task (excluding subtasks). - `totalTrackedDuration` integer, nullable: The summed up duration of all time trackings for this task, including subtasks. - `totalPlannedDuration` integer, nullable: The total planned workload of the task, in seconds, including subtasks. - `resourceVersion` integer: The version of the entity, updated on every modification, to the ticks in UTC. Not identical to UpdatedOn. - `checklistItemsDoneCount` integer: The number of checklist items marked as done. - `checklistItemsCount` integer: The total number of checklist items. - `taskSchedulesCount` integer: The number of task schedules for this task. - `isCompletelyScheduled` boolean: Whether this task is completed scheduled. - `commentCount` integer: The number of comments on this task. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `404`: Not Found ## Changes - **2026-10-13** `ab257be657b1`: 1 info - added the optional property `deriveDatesFromSubtasks` to the response with the `200` status - **2026-09-17** `1556e0487867`: 1 warning, 1 info - deleted the `header` request parameter `Authorization` - the endpoint scheme security `oauth2` was added to the API - **2026-09-12** `8e46cf415581`: 1 info - api operation id `GetTasksKeyByTaskIdentifier` removed and replaced with `tasks_GetTasksKeyByTaskIdentifier` - **2026-08-21** `a13e7c704262`: 1 info - response property `entityId` deprecated [Operation history](https://skmtc.dev/awork-io/apis/awork-io/changes/tasks/key/:taskIdentifier/get.md) --- [API](https://skmtc.dev/awork-io/apis/awork-io.md) - [All operations](https://skmtc.dev/awork-io/apis/awork-io/llms.txt) - [OpenAPI document](https://skmtc.dev/awork-io/apis/awork-io/revisions/81151fac7e79?raw)