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

# Run agent synchronously

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

## Request

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

Execute an agent run in a blocking manner and return the complete result once finished. A run still going after 8 minutes keeps running, and the request returns `202 Accepted` with code `run_still_running`, the `runId`, and a `Location` header pointing at `/api/agents/:agentId/run-async/:runId/status`; poll it (after `Retry-After` seconds) and read `/api/agents/:agentId/run-async/:runId/result` once it is `done`. Use `/api/agents/:agentId/run-async` for runs that can take longer.

## 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

- union: The complete result, or with 202 Accepted, where to find the result of a run that is still going
  - object: Complete result of synchronous agent execution
    - `finalAssistantMessage` string, required: The final text response from the assistant
    - `allToolCallsMade` object[], required: All tool calls made during the agent run
      - `type` 'tool-call', required
      - `toolCallId` string, required
      - `toolName` string, required
      - `args` unknown
    - `allToolResultsReceived` object[], required: All tool results received during the agent run
      - `type` 'tool-result', required
      - `toolCallId` string, required
      - `toolName` string, required
      - `result` unknown
      - `isError` boolean
    - `messages` union[], required: Complete message history from the agent run
      - union
        - object
          - `role` 'system', required
          - `content` string, required
        - object
          - `role` 'user', required
          - `content` union, required
            - string
            - union[]
              - …
        - object
          - `role` 'assistant', required
          - `content` union, required
            - string
            - union[]
              - …
        - object
          - `role` 'tool', required
          - `content` object[], required
            - `type` 'tool-result', required
            - `toolCallId` string, required
            - `toolName` string, required
            - `result` unknown
            - `isError` boolean
    - `structuredOutputResult` union: A JSON value (string, number, boolean, null, array, or object)
      - string
      - number
      - boolean
      - JsonValue[]
      - object
  - object: Sent with 202 Accepted when the run is still going at the response deadline
    - `code` 'run_still_running', required: Marks a run that is still going, not a result
    - `runId` string, uuid, required: Unique identifier of the run, which keeps going
    - `statusPath` string, required: Path to poll for the run status; also sent as the Location header
    - `resultPath` string, required: Path to read the result from once the status is `done`

## Other responses

- `202`: The run is still going at the 8-minute response deadline. `Location` points at its status endpoint.
- `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)