---
title: "Ask an agent on a call, deal or account"
method: POST
path: "/agents/ask"
tags: ["Agents"]
---

# Ask an agent on a call, deal or account

`POST /agents/ask`

## Request

- Base URL: `https://api.modjo.ai/v2`
- URL: `https://api.modjo.ai/v2/agents/ask`
- Auth: HTTP bearer

Asks the Modjo AI on a single call, deal or account and waits for the answer, returned as JSON matching the provided schema. The answer is generated by an artificial intelligence system and can be inaccurate, so review it before relying on it and disclose to end users that it was generated by AI. Answers usually take 30 seconds to 2 minutes and can take up to 5 minutes, so set your HTTP client timeout to at least 300 seconds. 502 and 504 errors are safe to retry. With `background: true`, the API answers `202` at once instead, and you read the result with `GET /agents/ask/{runUuid}`. This is a private feature: contact your Modjo account manager to learn more and request access.

## Request body

- AgentAskRequest
  - `scope` union, required: The entity the question is asked on. A call must be fully processed (status `completed`).
    - object
      - `type` 'call', required
      - `id` union, required: Call ID (positive integer) or UUID
        - integer
        - string, uuid
    - object
      - `type` 'deal', required
      - `id` integer, required: Deal ID
    - object
      - `type` 'account', required
      - `id` integer, required: Account ID
  - `instructions` string: Optional free-text guidance for the model, on top of the schema descriptions.
  - `responseFormat` AgentAskResponseFormat, required: Output format, using the same shape as the OpenAI `response_format` parameter with `type: "json_schema"`.
    - `type` 'json_schema', required
    - `json_schema` object, required
      - `name` string, required
      - `description` string
      - `schema` object, required: A JSON Schema describing the expected output, limited to `object` with `properties`, `array` with `items`, `string`, `number`, `integer`, `boolean` and `enum` on scalars. Keywords such as `minLength`, `minimum`, `pattern`, `format`, `$ref`, `oneOf` or `allOf` are refused. At most 100 properties, 5 nesting levels and 100 values per `enum`. Use property `description`s to tell the model what to extract.
      - `strict` boolean: Accepted for OpenAI compatibility. Strict mode is always on.
  - `background` boolean: Runs the analysis in the background: the API answers `202` at once with the run, whose result you read with `GET /agents/ask/{runUuid}`.

## Response `200`

Structured answer

- AgentAskResponse
  - `id` string, required: Identifier of the AI run. Share it with Modjo support when reporting an unexpected answer.
  - `scope` union, required: The entity the question is asked on. A call must be fully processed (status `completed`).
    - object
      - `type` 'call', required
      - `id` union, required: Call ID (positive integer) or UUID
        - integer
        - string, uuid
    - object
      - `type` 'deal', required
      - `id` integer, required: Deal ID
    - object
      - `type` 'account', required
      - `id` integer, required: Account ID
  - `output` object, required: The AI-generated answer, shaped by `responseFormat.json_schema.schema`. Every field of the schema is present, and a field the data does not answer is `null`.

## Other responses

- `202`: Background run started
- `400`: Invalid request body, or a JSON Schema outside the supported subset
- `401`: Authentication failed. The API key is missing or invalid.
- `403`: Agents, or background runs, are a private feature and are not enabled for this workspace
- `404`: Call, deal or account not found
- `409`: The call is not processed yet or has failed
- `429`: Rate limit exceeded. Retry after the X-RateLimit-Reset interval.
- `500`: The background run could not be started. Safe to retry.
- `502`: The AI failed to answer. Safe to retry.
- `504`: The AI did not answer in time. Safe to retry.

## Changes

- **2026-10-29** `8c6aa3426d23`: 3 info
  - added the new optional request property `background`
  - added the non-success response with the status `500`
  - added the success response with the status `202`
- **2026-10-02** `1f66d3efa41a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/modjo/apis/modjo-public-api/changes/agents/ask/post.md)

---

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