---
title: "List async operations"
method: GET
path: "/v1/default/banks/{bank_id}/operations"
tags: ["Operations"]
---

# List async operations

`GET /v1/default/banks/{bank_id}/operations`

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/operations`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/operations/get.ts> (a function with typed inputs; its response is checked against the schema)

Get a list of async operations for a specific agent, with optional filtering by status and operation type. Results are sorted by most recent first.

## Path parameters

- `bank_id` string, required

## Query parameters

- `status` string, nullable: Filter by status: pending, processing, completed, failed, or cancelled
- `type` string, nullable: Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery
- `limit` integer: Maximum number of operations to return
- `offset` integer: Number of operations to skip
- `exclude_parents` boolean: Exclude parent batch operations from results

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- OperationsListResponse: Response model for list operations endpoint.
  - `bank_id` string, required
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `operations` OperationResponse[], required
    - `id` string, required
    - `task_type` string, required
    - `operation_id` string, nullable: Same as `id`; the name the single-operation read uses.
    - `operation_type` string, nullable: Same as `task_type`; the name the single-operation read uses.
    - `items_count` integer, required
    - `document_id` string, nullable
    - `filename` string, nullable: Original filename for file-conversion operations (file_convert_retain); null for other task types.
    - `mental_model_id` string, nullable: Mental model this operation acted on (refresh_mental_model); null for other task types. Without it the list cannot say which model an operation refreshed — `document_id` is null for these, and the list carries no result_metadata.
    - `details` RefreshMentalModelOperationDetails: What a refresh_mental_model operation did, on the operation record itself. Reported under an async operation's ``details``, which is keyed by ``operation_type``: each type that has a typed outcome to report contributes its own shape there, rather than every type's fields being flattened onto the operation. Today refresh is the only one. This exists because ``result_metadata`` — the only per-refresh record kept indefinitely — could not say what a refresh did (#3274), and is documented as debug-only and unstable, so it is not something a caller can build on.
      - `operation_type` 'refresh_mental_model': Discriminator: which operation type this detail describes.
      - `outcome` 'content_written' | 'content_unchanged' | 'content_preserved_no_new_facts' | 'refresh_failed_empty_candidate' | 'refresh_failed_delta_not_applied' | 'refresh_failed_structured_output' | 'refresh_failed_candidate_rejected' | 'refresh_failed_error', required: What the refresh did with the document: rewrote it (`content_written`), produced a document identical to the stored one (`content_unchanged`), had no new facts to read at all (`content_preserved_no_new_facts`), or refused to write (the `refresh_failed_*` values).
      - `failure_reason` 'empty_candidate' | 'structured_doc_unreadable' | 'delta_ops_failed' | 'delta_ops_all_skipped' | 'delta_not_applied' | 'structured_output_failed' | 'candidate_rejected' | 'retrieval_failed' | 'no_answer' | 'unexpected_error', nullable: Why the refresh refused to write, finer-grained than the outcome — it distinguishes an op call that failed from one whose operations were all rejected, and from a baseline document that could not be read. Null unless `outcome` is one of the `refresh_failed_*` values.
    - `created_at` string, required
    - `updated_at` string, nullable: When this operation's row last changed (claim, progress heartbeat, or completion).
    - `status` string, required
    - `error_message` string, nullable, required
    - `retry_count` integer, nullable: Number of times this operation has been retried after failure.
    - `next_retry_at` string, nullable: When the worker will next attempt this operation. For a pending operation, a value in the future indicates the task is waiting rather than available for immediate pickup — a refresh_mental_model held back by min_refresh_interval_seconds, or an extension raising DeferOperation until some backpressure window opens. It is not cleared when the task finally runs, so on a terminal operation it is a record of the last wait rather than a pending one: read it together with status.
    - `progress` OperationProgress: Last-known progress snapshot for a long-running async operation. Written at coarse phase/batch boundaries by the worker (consolidation, batch retain). Lets an operator polling the operation status API distinguish a healthy long-running job (``processed`` advancing across polls) from a frozen one (same numbers, no movement in ``at``). Absent (``null``) on operations that never reached a checkpoint — completed-instantly or pre-feature rows.
      - `stage` string, required: Coarse phase the operation last reported (e.g. 'processing_batch').
      - `at` string, required: ISO-8601 timestamp when this snapshot was written.
      - `processed` integer, nullable: Units of work finished so far (sub-batches, memories), when known.
      - `total` integer, nullable: Total units of work for the operation, when known.
      - `detail` object, nullable: Operation-specific counters (e.g. observations_created, round, items_in_sub_batch).

## Other responses

- `404`: The bank does not exist.
- `422`: Validation Error

## Changes

- **2026-11-07** `45e711cd0897`: 2 warning
  - added the new `candidate_rejected` enum value to the `operations/items/details/anyOf[subschema #1: RefreshMentalModelOperationDetails]/failure_reason/anyOf[subschema #1]/` response property for the response status `200`
  - added the new `refresh_failed_candidate_rejected` enum value to the `operations/items/details/anyOf[subschema #1: RefreshMentalModelOperationDetails]/outcome` response property for the response status `200`
- **2026-10-04** `4fda98b75f63`: 1 warning, 8 info
  - removed the optional property `detail/items/url` from the response with the `422` status
  - added the non-success response with the status `404`
  - added the optional property `operations/items/details` to the response with the `200` status
  - added the optional property `operations/items/filename` to the response with the `200` status
  - …5 more
- **2026-05-15** `0d08f271b9db`: 6 info
  - added the new optional `query` request parameter `exclude_parents`
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
  - added the optional property `detail/items/url` to the response with the `422` status
  - …2 more

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/operations/get.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/45e711cd0897?raw)