---
title: "List routine runs"
method: GET
path: "/routines/{id}/runs"
tags: ["Routines"]
---

# List routine runs

`GET /routines/{id}/runs`

## Request

- Base URL: `https://elicit.com/api/v2`
- URL: `https://elicit.com/api/v2/routines/{id}/runs`
- Auth: HTTP bearer

Returns run history newest first. The default page size is 50 and the maximum is 100. Pass `nextCursor` back unchanged; a cursor issued for another routine returns `400 invalid_cursor`.

A terminal run can contain a summary and references to messages or artifacts in the attached Research Agent session. Failure codes identify dispatch, timeout, prerequisite, agent-turn, or output-conflict failures.

## Path parameters

- `id` string, uuid, required: Routine ID returned by a routine list or create response.

## Query parameters

- `limit` integer: Page size.
- `cursor` string: Opaque nextCursor from the previous run-history page.

## Response `200`

One page of routine runs.

- RoutineRunList
  - `runs` object[], required
    - `id` string, uuid, required
    - `taskId` string, uuid, required
    - `status` 'running' | 'output_ready' | 'no_output' | 'failed' | 'cancelled', required
    - `startedAt` string, required
    - `completedAt` string, nullable, required
    - `result` object, nullable, required
      - `version` 1, required
      - `summary` string
      - `effectRefs` union[], required
        - union
          - object
            - `type` 'message', required
            - `toolCallId` string, required
          - object
            - `type` 'artifact', required
            - `artifactKey` string, required
      - `startedBeforeLifecycleChange` boolean
    - `failure` object, nullable, required
      - `version` 1, required
      - `code` 'dispatch_failed' | 'timeout' | 'prerequisite_task_owner_access' | 'prerequisite_session_unavailable' | 'prerequisite_session_owner_ineligible' | 'agent_turn_failed' | 'output_conflict' | 'unknown', required
      - `message` string
  - `nextCursor` string, nullable, required: Cursor for the next page, or null at the end.

## Other responses

- `400`: A path ID, query parameter, body field, schedule, cursor, or filter/sort combination is invalid.
- `401`: Authentication failed. The API key is missing, invalid, revoked, or expired.
- `403`: API access or routines are unavailable for your account. Check the error code.
- `404`: The routine or requested session does not exist or is not accessible to you.
- `429`: Rate limit exceeded. More than 100 requests per minute were received from your IP address; further requests are blocked for 5 minutes.
- `500`: An unexpected error occurred. Retry reads with backoff; before retrying a write, check whether it took effect. See Error Handling for retry guidance.

## Changes

- **2026-10-13** `27c80b9a3470`: 5 info
  - added the optional property `error/details` to the response with the `400` status
  - added the optional property `error/details` to the response with the `401` status
  - added the optional property `error/details` to the response with the `403` status
  - added the optional property `error/details` to the response with the `404` status
  - …1 more
- **2026-10-02** `f9a4c55b1cde`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/elicit/apis/elicit-api/changes/routines/:id/runs/get.md)

---

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