---
title: "Poll for triggers (tasks, mentions)"
method: GET
path: "/api/poll"
tags: ["Poll"]
---

# Poll for triggers (tasks, mentions)

`GET /api/poll`

## Response `200`

Trigger data or null

- object
  - `trigger` union, required
    - object
      - `type` 'task_offered', required
      - `taskId` string, required
      - `task` AgentTask, 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` '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
      - `type` 'task_assigned', required
      - `taskId` string, required
      - `task` 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` '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[]
        - `attachments` object[], required
          - `id` string, uuid, required
          - `name` string, required
          - `mimeType` string
          - `sizeBytes` integer
      - `requestedBy` object
        - `name` string, required
        - `email` string
        - `role` string
        - `notes` string
    - BudgetRefusedTrigger
      - `type` 'budget_refused', required
      - `cause` 'agent' | 'global' | 'user', required
      - `agentSpend` number
      - `agentBudget` number
      - `globalSpend` number
      - `globalBudget` number
      - `userSpend` number
      - `userBudget` number
      - `resetAt` string, required
    - object
      - `type` 'unread_mentions', required
      - `mentionsCount` number, required
      - `claimedChannels` string[], required
    - object
      - `type` 'channel_activity', required
      - `count` number, required
      - `messages` object[], required
        - `channelId` string, required
        - `channelName` string
        - `ts` string, required
        - `user` string, required
        - `text` string, required
      - `cursorUpdates` object[], required
        - `channelId` string, required
        - `ts` string, required

## Other responses

- `400` — Missing X-Agent-ID
- `404` — Agent not found

---

[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/0375890be8c4/schema)