---
title: "Get an AI Agent Task"
method: GET
path: "/v1/ai/agents/tasks/{taskId}"
tags: ["AI Agent Tasks"]
---

# Get an AI Agent Task

`GET /v1/ai/agents/tasks/{taskId}`

Returns the details of a specific AI agent task including its current status and pending decisions.

## Path parameters

- `taskId` string, uuid, required

## Response `200`

Agent task retrieved successfully

- GetTaskResponse
  - `agentConfig` DataEngineerAgentConfig
    - `name` string, required — The agent type identifier. Must be "data_engineer_agent"
    - `environmentName` string, required — The name of the environment to use for execution
    - `generateBranch` boolean — Whether the agent should auto-generate a new branch for its changes
    - `graphId` string, nullable — The ID of the pipeline graph the agent will work on
    - `mode` 'PLAN' | 'ACT', required — The execution mode. ACT allows the agent to make changes; PLAN produces a plan only
    - `projectId` string, uuid, required — The ID of the project the agent will work within
    - `sourceBranchName` string, required — The branch the agent will read from
    - `targetBranchName` string, nullable — The branch the agent will write changes to. Required unless generateBranch is true
    - `workingDirectory` string, nullable — The working directory within the project for the agent
  - `createdAt` string, date-time — The date and time the task was created
  - `description` string — A short description of what the agent was asked to do
  - `grantedPermissions` AllowedTool[] — Permissions that have been granted to the agent for this task
    - `toolName` string, required — The name of the tool to allow
  - `modifiedAt` string, date-time — The date and time the task was last modified
  - `pendingDecisions` PendingPermission[] — Decisions awaiting approval before the agent can proceed
    - `permissionMessage` PermissionMessage
      - `body` string — A detailed description of the permission being requested
      - `title` string — A short title summarising the permission request
    - `toolId` string — The unique identifier of the tool invocation
    - `toolInput` unknown
    - `toolName` string — The name of the tool requesting permission
    - `type` 'tool' | 'question' — The type of decision required
  - `status` 'RUNNING' | 'STOPPED' | 'STOPPING' | 'ERRORED' — The current status of the task
  - `taskId` string, uuid — The unique identifier of the task

## Other responses

- `400` — Invalid request parameters
- `401` — Missing or invalid authentication token
- `403` — Insufficient permissions to retrieve the agent task
- `404` — Task not found
- `502` — Upstream service error
- `504` — Upstream service timeout

---

[API](https://skmtc.net/maia/apis/maia-public-rest-api.md) · [All operations](https://skmtc.net/maia/apis/maia-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia/maia-public-rest-api/revisions/6239825f68eb/schema)