---
title: "Run a tool in an external task"
method: POST
path: "/v1/tasks/{taskId}/tool-calls"
tags: ["Adam API"]
---

# Run a tool in an external task

`POST /v1/tasks/{taskId}/tool-calls`

## Request

- Base URL: `https://api.adam.new`
- URL: `https://api.adam.new/v1/tasks/{taskId}/tool-calls`
- 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:write`, `tools:execute`
- TypeScript: <https://skmtc.dev/adam/apis/adam-api/docs/v1/tasks/:taskId/tool-calls/post.ts> (a function with typed inputs; its response is checked against the schema)

Queue a tool call for an external task you own. Use a tool name and input schema from listTaskTools. This runs the selected tool without an Adam agent or model loop; tools may provision compute, use connected accounts or credentials, and incur usage charges. Poll getToolCall for the outcome. An unknown outcome must not be retried with a new key because the operation may have taken effect.

## Path parameters

- `taskId` string, uuid, required

## Headers

- `Idempotency-Key` string, required

## Request body

- CallPublicTaskToolRequestDto
  - `tool` string, required
  - `input` object, required

## Response `202`

- GetPublicToolCallResponseDto
  - `call` object, required
    - `id` string, uuid, required
    - `taskId` string, uuid, required
    - `tool` string, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown', required
    - `input` object, required
    - `output` union, required
      - string
      - number
      - boolean
      - GetPublicToolCallResponseDtoSchema0[]
      - object
    - `error` object, nullable, required
      - `code` string, required
      - `message` string, required
    - `createdAt` string, required
    - `startedAt` string, nullable, required
    - `finishedAt` string, nullable, 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`: 2 breaking, 2 info
  - the response property `call/finishedAt` became nullable for the status `202`
  - the response property `call/startedAt` became nullable for the status `202`
  - response property `call/finishedAt` list-of-types was narrowed by removing types `null` from media type `application/json` of response `202`
  - response property `call/startedAt` list-of-types was narrowed by removing types `null` from media type `application/json` of response `202`
- **2026-10-09** `135cef4f7586`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adam/apis/adam-api/changes/v1/tasks/:taskId/tool-calls/post.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)