--- title: "Run a query template" method: POST path: "/v2/{ledger}/queries/{id}/run" tags: ["ledger.v2"] --- # Run a query template `POST /v2/{ledger}/queries/{id}/run` Run a query template on a ledger ## Path parameters - `ledger` string, required - `id` string, required ## Query parameters - `schemaVersion` string, required - `pageSize` integer - `cursor` string - `expand` string - `pit` string, date-time - `order` 'effective' - `reverse` boolean - `sort` string ## Request body - object - `cursor` string - `params` union — Parameters applied when running a query template - object - `pageSize` integer — The maximum number of results to return per page. - `cursor` string — Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. - `expand` string — Additional data to include in the response, such as volumes - `pit` string, date-time — Point-in-time. Returns the state as it existed at this timestamp - `sort` string — Sort results using a field name and order (ascending or descending). Format: `:`, where `` is the field name and `` is either `asc` or `desc`. - `resource` 'accounts', required - object - `pageSize` integer — The maximum number of results to return per page. - `cursor` string — Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. - `expand` string — Additional data to include in the response, such as volumes - `pit` string, date-time — Point-in-time. Returns the state as it existed at this timestamp - `sort` string — Sort results using a field name and order (ascending or descending). Format: `:`, where `` is the field name and `` is either `asc` or `desc`. - `resource` 'transactions', required - object - `pageSize` integer — The maximum number of results to return per page. - `cursor` string — Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. - `expand` string — Additional data to include in the response, such as volumes - `pit` string, date-time — Point-in-time. Returns the state as it existed at this timestamp - `sort` string — Sort results using a field name and order (ascending or descending). Format: `:`, where `` is the field name and `` is either `asc` or `desc`. - `resource` 'logs', required - object - `pageSize` integer — The maximum number of results to return per page. - `cursor` string — Parameter used in pagination requests. Maximum page size is set to 15. Set to the value of next for the next page of results. Set to the value of previous for the previous page of results. No other parameters can be set when this parameter is set. - `expand` string — Additional data to include in the response, such as volumes - `pit` string, date-time — Point-in-time. Returns the state as it existed at this timestamp - `sort` string — Sort results using a field name and order (ascending or descending). Format: `:`, where `` is the field name and `` is either `asc` or `desc`. - `resource` 'volumes', required - `insertionDate` boolean - `groupBy` integer - `vars` object ## Response `200` OK - union - V2TransactionsCursorResponse - `resource` 'transactions' — The resource type carried by this cursor - `cursor` object, required — Paginated cursor wrapping the list of transactions - `pageSize` integer, required - `hasMore` boolean, required - `previous` string - `next` string - `data` V2Transaction[], required - `insertedAt` string, date-time — The request time: when the transaction was actually written to the ledger. Set by the ledger, not the caller. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `updatedAt` string, date-time — When the transaction row was last modified, for example by a metadata change or a revert - `timestamp` string, date-time, required — The transaction time: when the transaction is considered to have occurred, also called the effective or booking date. This is the axis the ledger uses to compute balances and resolve point-in-time queries. Settable at creation, defaulting to current machine time if omitted, and immutable once written. See [bi-temporality](https://docs.formance.com/modules/ledger/working-with/bi-temporality) - `postings` V2Posting[], required — The fund movements making up the transaction - `amount` integer, required — Amount to move, as an arbitrary-precision integer expressed in the asset's smallest unit - `asset` string, required — The asset being moved, optionally carrying a scale suffix such as USD/2 - `destination` string, required — Address of the account credited by this posting - `source` string, required — Address of the account debited by this posting - `reference` string — Optional caller-supplied identifier, unique within the ledger, used to deduplicate transactions - `metadata` V2Metadata, required — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - `id` integer, required — Unique sequential identifier for this transaction within the ledger - `reverted` boolean, required — Indicates if the transaction has been reverted - `revertedAt` string, date-time — When the transaction was reverted, on the request-time axis. Absent if the transaction has not been reverted - `preCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `preCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `postCommitEffectiveVolumes` V2AggregatedVolumes — Volumes aggregated per account and per asset - `template` string — Name of the transaction template this transaction was created from, if any - V2AccountsCursorResponse - `resource` 'accounts' — The resource type carried by this cursor - `cursor` object, required — Paginated cursor wrapping the list of accounts - `pageSize` integer, required - `hasMore` boolean, required - `previous` string - `next` string - `data` V2Account[], required - `address` string, required — The account address, a colon-separated segmented path such as users:001 - `metadata` object, required — Arbitrary key/value pairs attached to the account. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - `insertionDate` string, date-time — When the account was first written to the ledger, on the request-time axis - `updatedAt` string, date-time — When the account was last modified, for example by a metadata change - `firstUsage` string, date-time — Transaction time of the earliest transaction touching this account. Inserting a backdated transaction can move it earlier - `volumes` V2Volumes — Volumes per asset for a single account - `effectiveVolumes` V2Volumes — Volumes per asset for a single account - V2LogsCursorResponse - `resource` 'logs' — The resource type carried by this cursor - `cursor` object, required — Paginated cursor wrapping the list of logs - `pageSize` integer, required - `hasMore` boolean, required - `previous` string - `next` string - `data` V2Log[], required - `id` integer, required — Unique sequential identifier for this log entry within the ledger - `type` 'NEW_TRANSACTION' | 'SET_METADATA' | 'REVERTED_TRANSACTION' | 'DELETE_METADATA' | 'INSERTED_SCHEMA', required — The type of operation this log represents - `data` union, required — The payload of the log entry. Structure depends on the log type: - NEW_TRANSACTION: V2LogDataNewTransaction - SET_METADATA: V2LogDataSetMetadata - REVERTED_TRANSACTION: V2LogDataRevertedTransaction - DELETE_METADATA: V2LogDataDeleteMetadata - INSERTED_SCHEMA: V2LogDataInsertedSchema - V2LogDataNewTransaction — Payload for NEW_TRANSACTION log entries. Contains the created transaction and any account metadata set during creation. - `transaction` V2LogTransaction, required — Transaction structure as it appears in log payloads - … - `accountMetadata` object, required — Metadata applied to accounts involved in the transaction - V2LogDataSetMetadata — Payload for SET_METADATA log entries. Contains the target entity and the metadata that was set. - `targetType` 'ACCOUNT' | 'TRANSACTION', required — Type of the target entity - `targetId` union, required — Identifier of the entity the metadata was set on, either an account address or a transaction ID - … - `metadata` V2Metadata, required — Arbitrary key/value pairs attached to the resource. Metadata is bi-temporal, so a point-in-time query returns the metadata as it stood at that time - V2LogDataRevertedTransaction — Payload for REVERTED_TRANSACTION log entries. Contains both the original reverted transaction and the new reverting transaction. - `revertedTransaction` V2LogTransaction, required — Transaction structure as it appears in log payloads - … - `transaction` V2LogTransaction, required — Transaction structure as it appears in log payloads - … - V2LogDataDeleteMetadata — Payload for DELETE_METADATA log entries. Contains the target entity and the metadata key that was deleted. - `targetType` 'ACCOUNT' | 'TRANSACTION', required — Type of the target entity - `targetId` union, required — Identifier of the entity the metadata was deleted from, either an account address or a transaction ID - … - `key` string, required — The metadata key that was deleted - V2LogDataInsertedSchema — Payload for INSERTED_SCHEMA log entries. Contains the schema that was inserted into the ledger. - `schema` V2Schema, required — Schema data structure for ledger schemas - … - `hash` string, required — SHA256 hash of the log entry, chained from the previous log for integrity verification - `date` string, date-time, required — Timestamp when the operation was recorded - `schemaVersion` string — Schema version used for validation when the log was created - V2VolumesWithBalanceCursorResponse - `resource` 'volumes' — The resource type carried by this cursor - `cursor` object, required — Paginated cursor wrapping the list of volumes - `pageSize` integer, required - `hasMore` boolean, required - `previous` string - `next` string - `data` V2VolumesWithBalance[], required - `account` string, required — The account address these volumes belong to - `asset` string, required — The asset these volumes are denominated in - `input` integer, required — Total amount credited to the account for this asset - `output` integer, required — Total amount debited from the account for this asset - `balance` integer, required — Net balance for this asset, equal to input minus output ## Other responses - `default` — Error ## Changes - **2026-08-28** `fe945da1b75d` — 12 breaking, 18 warning, 2 info - the `oneOf[#/components/schemas/V2LogsCursorResponse]/cursor/data/items/data/oneOf[#/components/schemas/V2LogDataRevertedTransaction]/revertedTransaction` response's property type/format changed from `object`/`` to ``/`` for status `200` - the `oneOf[#/components/schemas/V2LogsCursorResponse]/cursor/data/items/data/oneOf[#/components/schemas/V2LogDataRevertedTransaction]/transaction` response's property type/format changed from `object`/`` to ``/`` for status `200` - removed the required property `oneOf[#/components/schemas/V2LogsCursorResponse]/cursor/data/items/data/oneOf[#/components/schemas/V2LogDataRevertedTransaction]/revertedTransaction/id` from the response with the `200` status - removed the required property `oneOf[#/components/schemas/V2LogsCursorResponse]/cursor/data/items/data/oneOf[#/components/schemas/V2LogDataRevertedTransaction]/revertedTransaction/metadata` from the response with the `200` status - …28 more - …earlier changes not shown [Full history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v2/:ledger/queries/:id/run/post.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-service-production.skmtc.workers.dev/v1/apis/formancehq/ledger-api/revisions/fe945da1b75d/schema)