---
title: "List tasks with filters"
method: GET
path: "/api/tasks"
tags: ["Tasks"]
---

# List tasks with filters

`GET /api/tasks`

Returns tasks with the full `task` text replaced by a bounded `taskPreview` and completion/integration blobs dropped by default — list views only need the preview. Pass `fields=full` to restore the full `AgentTask`. Fetch a single task in full via `GET /api/tasks/{id}`.

## Query parameters

- `status` string
- `agentId` string
- `scheduleId` string
- `key` string — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
- `keyPrefix` string — Non-unique asset directory namespace (for example shared/ or personal/<user-id>/drafts/). Runtime write boundaries normalize and validate the canonical form.
- `search` string
- `includeHeartbeat` 'true' | 'false'
- `createdAfter` string, date-time
- `createdBefore` string, date-time
- `source` string
- `requestedByUserId` string
- `orderBy` 'lastUpdatedAt' | 'createdAt'
- `limit` integer, nullable
- `offset` integer, nullable
- `fields` 'full' | 'slim'

## Response `200`

Paginated task list

- object
  - `tasks` union, required
    - AgentTask[]
      - `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` 'backlog' | 'unassigned' | 'offered' | 'reviewing' | 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'superseded', required
      - `source` 'mcp' | 'slack' | 'api' | 'ui' | 'github' | 'gitlab' | 'agentmail' | 'system' | 'schedule' | 'workflow' | 'linear' | 'jira'
      - `taskType` string
      - `tags` string[]
      - `priority` integer
      - `dependsOn` string[]
      - `offeredTo` string
      - `offeredAt` string, date-time
      - `acceptedAt` string, date-time
      - `rejectionReason` string
      - `createdAt` string, date-time, required
      - `lastUpdatedAt` string, date-time, required
      - `finishedAt` string, date-time
      - `notifiedAt` string, date-time
      - `failureReason` string
      - `output` string
      - `progress` string
      - `slackChannelId` string
      - `slackThreadTs` string
      - `slackTriggerMessageTs` string
      - `slackUserId` string
      - `slackReplySent` boolean
      - `slackProgressMessageTs` string
      - `slackTreeRootMessageTs` string
      - `vcsProvider` 'github' | 'gitlab'
      - `vcsRepo` string
      - `vcsEventType` string
      - `vcsNumber` integer
      - `vcsCommentId` integer
      - `vcsAuthor` string
      - `vcsUrl` string
      - `vcsInstallationId` integer
      - `vcsNodeId` string
      - `agentmailInboxId` string
      - `agentmailMessageId` string
      - `agentmailThreadId` string
      - `mentionMessageId` string
      - `mentionChannelId` string
      - `dir` string
      - `parentTaskId` string
      - `claudeSessionId` string
      - `model` string
      - `modelTier` 'smol' | 'regular' | 'smart' | 'ultra'
      - `effort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
      - `scheduleId` string
      - `workflowRunId` string, uuid, nullable
      - `workflowRunStepId` string, uuid, nullable
      - `contextKey` string
      - `outputSchema` object
      - `followUpConfig` FollowUpConfig
        - `disabled` boolean
        - `onCompleted` string
        - `onFailed` string
      - `wasPaused` boolean
      - `compactionCount` integer
      - `peakContextPercent` number
      - `peakContextTokens` integer
      - `contextWindowSize` integer
      - `credentialKeySuffix` string
      - `credentialKeyType` string
      - `requestedByUserId` string
      - `swarmVersion` string
      - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
      - `providerMeta` object
      - `harnessVariant` string
      - `harnessVariantMeta` object
      - `totalCostUsd` number
      - `routingAffinity` RoutingAffinity
        - `sourceAgentId` string
        - `role` string
        - `harnessProvider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
        - `capabilities` string[]
    - object[]
      - `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` 'backlog' | 'unassigned' | 'offered' | 'reviewing' | 'pending' | 'in_progress' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'superseded', required
      - `source` 'mcp' | 'slack' | 'api' | 'ui' | 'github' | 'gitlab' | 'agentmail' | 'system' | 'schedule' | 'workflow' | 'linear' | 'jira'
      - `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'
      - `effort` 'off' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
      - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode'
      - `requestedByUserId` string
      - `progress` string
      - `createdAt` string, date-time, required
      - `lastUpdatedAt` string, date-time, required
      - `finishedAt` string, date-time
      - `peakContextPercent` number
      - `totalCostUsd` number
  - `total` integer, required

## Other responses

- `400` — Validation error (e.g. unknown status token)

---

[API](https://skmtc.net/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.net/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/desplega-ai/agent-swarm-api/versions/ef761849166b/schema)