---
title: "Inspect an external task subagent"
method: GET
path: "/v1/tasks/{taskId}/subagents/lookup"
tags: ["Adam API"]
---

# Inspect an external task subagent

`GET /v1/tasks/{taskId}/subagents/lookup`

## Request

- Base URL: `https://api.adam.new`
- URL: `https://api.adam.new/v1/tasks/{taskId}/subagents/lookup`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.adam.new/auth/oauth2/authorize`
    - Token URL: `https://api.adam.new/auth/oauth2/token` scopes: `tasks:read`, `tools:execute`
- TypeScript: <https://skmtc.dev/adam/apis/adam-api/docs/v1/tasks/:taskId/subagents/lookup/get.ts> (a function with typed inputs; its response is checked against the schema)

Return a subagent's status, result, and produced file references without starting a parent model turn. Supply exactly one of subagentId or toolCallId; the latter can recover a launch whose tool-call outcome is unknown. Requires tasks:read and tools:execute. Returns null when no matching subagent exists. Internal messages, model routes, and raw errors are omitted.

## Path parameters

- `taskId` string, uuid, required

## Query parameters

- `toolCallId` string, uuid
- `subagentId` string

## Response `200`

- GetPublicSubagentResponseDto
  - `subagent` object, nullable, required
    - `subagentId` string, uuid, required
    - `taskId` string, uuid, required
    - `toolCallId` string, nullable, required
    - `workerName` string, required
    - `status` 'idle' | 'draft' | 'streaming' | 'awaiting_tool_result' | 'completed' | 'failed', required
    - `stopCause` 'user' | 'parent' | 'parent_stopped', nullable, required
    - `active` boolean, required
    - `result` string, nullable, required
    - `error` string, nullable, required
    - `files` object[], required
      - `id` string, required
      - `name` string, nullable, required
      - `mediaType` string, required
    - `createdAt` string, required
    - `updatedAt` string, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid Bearer credential
- `402`: Payment or subscription required
- `403`: Credential is missing a required scope
- `404`: Resource not found
- `409`: Request conflict
- `429`: Rate limit exceeded
- `500`: Internal API error

## Changes

- **2026-10-29** `4baea94e5dbc`: 4 breaking, 4 info
  - the response property `subagent/anyOf[subschema #1]/error` became nullable for the status `200`
  - the response property `subagent/anyOf[subschema #1]/files/items/name` became nullable for the status `200`
  - the response property `subagent/anyOf[subschema #1]/result` became nullable for the status `200`
  - the response property `subagent/anyOf[subschema #1]/toolCallId` became nullable for the status `200`
  - …4 more
- **2026-10-09** `135cef4f7586`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adam/apis/adam-api/changes/v1/tasks/:taskId/subagents/lookup/get.md)

---

[API](https://skmtc.dev/adam/apis/adam-api.md) - [All operations](https://skmtc.dev/adam/apis/adam-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adam/apis/adam-api/revisions/38d4c566646c?raw)