---
title: "List agent runs"
method: GET
path: "/agents/ask"
tags: ["Agents"]
---

# List agent runs

`GET /agents/ask`

## Request

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

Lists the background runs of the last 7 days, newest first, to recover a run whose response was lost. Pages are read with a cursor: pass `pagination.nextCursor` as `cursor` to get the next page.

## Query parameters

- `status` 'queued' | 'processing' | 'completed' | 'failed': Only list the runs in this status
- `size` integer: Number of items per page
- `cursor` string: The `pagination.nextCursor` of the previous page

## Response `200`

Agent runs

- AgentRunList
  - `data` AgentRun[], required
    - `uuid` string, uuid, required: Run UUID, to read the run with `GET /agents/ask/{runUuid}`.
    - `status` 'queued' | 'processing' | 'completed' | 'failed', required: `queued` until a worker picks the run, `processing` while the AI answers (retries included), then `completed` or `failed`.
    - `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: The AI-generated answer once the run is `completed`, shaped by `responseFormat.json_schema.schema`. A field the data does not answer is `null`.
    - `error` object: Why the run failed, once it is `failed`.
      - `code` 'unsupported_schema' | 'invalid_text' | 'scope_not_found' | 'resolution_failed' | 'run_deadline_exceeded' | 'agent_loop_exceeded' | 'runtime_error' | 'upstream_timeout' | 'upstream_error' | 'internal_error', required
      - `message` string, required
    - `createdOn` string, date-time, required: When the run was created.
    - `finishedOn` string, date-time, nullable, required: When the run reached `completed` or `failed`, `null` before.
    - `expiresOn` string, date-time, required: The run is deleted after this date, 7 days after its creation.
  - `pagination` object, required
    - `size` integer, required: Requested page size
    - `nextCursor` string, nullable, required: Cursor of the next page, `null` on the last page

## Other responses

- `400`: Invalid query parameters or cursor
- `401`: Authentication failed. The API key is missing or invalid.
- `403`: Background runs are a private feature and are not enabled for this workspace
- `429`: Rate limit exceeded. Retry after the X-RateLimit-Reset interval.

## Changes

- **2026-10-29** `8c6aa3426d23`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/modjo/apis/modjo-public-api/changes/agents/ask/get.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)