---
title: "List prepared queries"
method: GET
path: "/v3/{ledgerName}/prepared-queries"
tags: ["Prepared Queries"]
---

# List prepared queries

`GET /v3/{ledgerName}/prepared-queries`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/{ledgerName}/prepared-queries`
- Auth: one of:
  - HTTP bearer
  - none

Returns a list of all prepared queries for a ledger. Requires `ledger:ReadQuery` scope.

## Path parameters

- `ledgerName` string, required

## Headers

- `X-Consistency` 'linearizable' | 'stale'

## Response `200`

List of prepared queries retrieved successfully

- ListPreparedQueriesResponse
  - `data` PreparedQuery[], required
    - `name` string, required: Query name
    - `target` 'ACCOUNTS' | 'TRANSACTIONS' | 'LOGS', required: Target entity type. `LOGS`, `ACCOUNTS` and `TRANSACTIONS` are all usable prepared-query targets (create, list/get and execute).
    - `filter` QueryFilter: Recursive filter expression using the Formance query DSL (aligned with the v2 API). Each node is an object with **exactly one** top-level `$`-prefixed operator key. Combinators: - `{"$and": [QueryFilter, ...]}` — all sub-filters must match (non-empty). - `{"$or": [QueryFilter, ...]}` — at least one sub-filter matches (non-empty). - `{"$not": QueryFilter}` — negates a single sub-filter. Leaf conditions are a single-key operator whose value is a `{ "<field>": <value> }` map with exactly one field: - `{"$match": {"<field>": <value>}}` — equality; for `address`/`source`/`destination` a trailing `:` means prefix match, otherwise exact. - `{"$gt"|"$gte"|"$lt"|"$lte": {"<field>": <value>}}` — range bound. A closed range is expressed as an `$and` of a lower and an upper bound on the same field. - `{"$exists": {"metadata": "<key>"}}` — the metadata key is present. - `{"$exists": {"asset": "<assetRef>"}}` — the account has ever held the asset (`assetRef` is `BASE` or `BASE/PRECISION`, e.g. `USD/2`). Requires a READY `account-asset` index. Supported fields: `metadata[<key>]`, `address`, `source`, `destination`, `reference`, `reverted` (bool), `ledger`, `id`, `timestamp`, `insertedAt`, `revertedAt`, `logId`, `date`. Not every field applies to every query target; a field that does not apply is rejected. On the numeric built-ins (`id`, `timestamp`, `insertedAt`, `revertedAt`, `logId`, `date`) use `$gt`/`$gte`/`$lt`/`$lte` for ranges; `$match` is an equality (the closed range from the value to itself). On the audit-entries endpoint only, the bare audit fields (`outcome`, `ledger`, `seq`, `proposal_id`, `timestamp`, `log_seq`, `caller_subject`, `order_type`, `idempotency_key`) replace the `ledger`/`timestamp` meanings above: `$match` on any of them, range operators on the numeric ones, no `$param` values. The log-only fields (`logId`, `date`, `ledger`) are valid only when the prepared query targets `LOGS`; they are rejected on `ACCOUNTS` and `TRANSACTIONS` targets. A value is either a JSON literal or a parameter reference `{"$param": "<name>"}`, resolved at prepared-query execution time. A JSON `null` in value position is rejected. uint64 fields (`id`, `timestamp`, `insertedAt`, `revertedAt`, `logId`, `date`) are carried as decimal strings to stay lossless above 2^53. The date-semantic fields (`timestamp`, `insertedAt`, `revertedAt`, `date`) additionally accept an RFC3339 timestamp string (e.g. `{"$gte":{"date":"2023-11-14T22:13:20Z"}}`), coerced to the same Unix microseconds as the raw form; a value before the Unix epoch (1970-01-01) is rejected.
      - `$and` QueryFilter[]
      - `$or` QueryFilter[]
      - `$not` QueryFilter (recursive)
      - `$match` object: `{ "<field>": <value> }` — exact/prefix/bool match.
      - `$gt` object: `{ "<field>": <value> }` — strictly greater than.
      - `$gte` object: `{ "<field>": <value> }` — greater than or equal.
      - `$lt` object: `{ "<field>": <value> }` — strictly less than.
      - `$lte` object: `{ "<field>": <value> }` — less than or equal.
      - `$exists` object: `{ "metadata": "<key>" }` (metadata key present) or `{ "asset": "<assetRef>" }` (account has held the asset).
      - `$in` object: `{ "<field>": [<value>, ...] }` — value is one of a set. Reserved for the list endpoints; not accepted on prepared queries yet.
    - `allowedModes` string[]

## Other responses

- `400`: Bad request
- `401`: Authentication required (missing or invalid JWT token)
- `403`: Insufficient permissions (missing required scope)
- `404`: Not found
- `405`: Method not allowed
- `500`: Internal server error
- `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`).

## Changes

- **2026-11-03** `f5e817eca038`: 1 info
  - api operation id `listPreparedQueries` removed and replaced with `v3ListPreparedQueries`
- **2026-10-08** `3da23d327316`: 2 info
  - added the media type `text/plain` for the response with the status `401`
  - added the media type `text/plain` for the response with the status `403`
- **2026-10-08** `b3ee1959d86a`: 1 info
  - added the new optional `header` request parameter `X-Consistency`
- **2026-10-01** `2587b9f91dd1`: 1 breaking
  - the response property `data/items/filter` became optional for the status `200`
- **2026-09-30** `b747efd5cd77`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/prepared-queries/get.md)

---

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