---
title: "Run agent asynchronously"
method: POST
path: "/api/agents/{agentId}/run-async"
tags: ["Agents"]
---

# Run agent asynchronously

`POST /api/agents/{agentId}/run-async`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agents/{agentId}/run-async`
- Auth: HTTP bearer

Start an asynchronous agent run and return a runId that can be polled for status updates. Once the run status is `done`, call `/api/agents/:agentId/run-async/:runId/result` to retrieve the same final payload shape returned by the synchronous run endpoint.

## Path parameters

- `agentId` string, uuid, required: Unique identifier of the agent to execute

## Request body

- object: Input values for agent execution, keyed by name and sent to the agent as its first message
  - `inputs` JsonObject, required: A JSON object whose values are valid JSON values
  - `attachments` object[]: Optional array of file attachments to include with the agent execution
    - `fileId` string, required: Unique identifier of the uploaded file
    - `fileName` string, required: Name of the file
    - `size` number, required: Size of the file in bytes
    - `fileType` 'image' | 'pdf' | 'spreadsheet' | 'document' | 'presentation' | 'file': Semantic file type for iconography
    - `previewText` string: Optional text preview for text-like files

## Response `200`

Successful response

- object: Response containing run ID for asynchronous agent execution
  - `runId` string, uuid, required: Unique identifier for this asynchronous agent run that can be polled for status

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

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