---
title: "Get the tree a task belongs to (ancestors and descendants)"
method: GET
path: "/api/tasks/{id}/lineage"
tags: ["Tasks"]
---

# Get the tree a task belongs to (ancestors and descendants)

`GET /api/tasks/{id}/lineage`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/tasks/{id}/lineage`
- Auth: HTTP bearer

Follows `parentTaskId` up to the topmost ancestor, then returns every descendant of that root as slim task rows, the task's own subtree first. Bounded: at most 50 hops up, `maxDepth` levels down and about twice `maxNodes` rows; `truncated` is true when any task in the tree is missing from the response.

## Path parameters

- `id` string, required

## Query parameters

- `maxNodes` integer
- `maxDepth` integer

## Response `200`

The lineage tree as a flat list linked by `parentTaskId`

- object
  - `rootTaskId` string, required
  - `tasks` object[], required
    - `id` string, uuid, required
    - `key` string, required: Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
    - `agentId` string, nullable, required
    - `creatorAgentId` string
    - `task` string, required
    - `title` string
    - `status` 'draft' | 'backlog' | 'unassigned' | 'offered' | 'reviewing' | 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'superseded', required
    - `source` 'mcp' | 'slack' | 'api' | 'ui' | 'github' | 'gitlab' | 'azure-devops' | 'bitbucket' | 'agentmail' | 'system' | 'schedule' | 'workflow' | 'linear' | 'jira' | 'comb' | 'chat'
    - `taskType` string
    - `tags` string[]
    - `priority` integer
    - `dependsOn` string[]
    - `offeredTo` string
    - `acceptedAt` string, date-time
    - `parentTaskId` string
    - `scheduleId` string
    - `model` string
    - `modelTier` 'smol' | 'regular' | 'smart' | 'ultra'
    - `resolvedModel` string
    - `modelSource` string
    - `modelAlias` string
    - `effort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `resolvedEffort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp' | 'dsh' | 'amp' | 'cursor' | 'grok' | 'fx'
    - `requestedByUserId` string
    - `progress` string
    - `createdAt` string, date-time, required
    - `lastUpdatedAt` string, date-time, required
    - `finishedAt` string, date-time
    - `peakContextPercent` number
    - `totalCostUsd` number
    - `workflowRunId` string
  - `truncated` boolean, required

## Other responses

- `403`: A user caller cannot read the task's session
- `404`: Task not found

## Changes

- **2026-10-29** `305e33634408`: 1 warning
  - added the new `fx` enum value to the `tasks/items/provider` response property for the response status `200`
- **2026-10-22** `9a8d9b86b25b`: 1 warning
  - added the new `bitbucket` enum value to the `tasks/items/source` response property for the response status `200`
- **2026-10-19** `cd4fc44c6803`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/tasks/:id/lineage/get.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)