---
title: "Analyze transaction flow patterns"
method: GET
path: "/v3/{ledgerName}/analyze-transactions"
tags: ["Transactions"]
---

# Analyze transaction flow patterns

`GET /v3/{ledgerName}/analyze-transactions`

## Request

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

Scans all transactions in a ledger, discovers flow patterns by normalizing
account addresses, and returns statistics per flow type including temporal
distribution and volume metrics. Requires `ledger:read` scope.

## Path parameters

- `ledgerName` string, required

## Query parameters

- `variableThreshold` integer

## Headers

- `X-Consistency` 'linearizable' | 'stale'
- `Formance-Bigint-As-String` string

## Response `200`

Analysis completed successfully

- AnalyzeTransactionsResponse
  - `data` object, required
    - `flowPatterns` FlowPattern[]
      - `signature` string: Canonical flow signature (e.g. "users:{id}:main->bank:fees[USD]")
      - `structure` 'simple' | 'multiSource' | 'multiDestination' | 'complex'
      - `transactionCount` integer
      - `postings` NormalizedPosting[]
        - `sourcePattern` string, required
        - `destinationPattern` string, required
        - `asset` string, required
        - `color` string, required: Color discriminates postings on the same (source, destination, asset) but different color buckets in the FSM. Always emitted (even empty) so clients can distinguish the uncolored bucket from patterns that differ only by color.
      - `temporal` TemporalStats
        - `firstSeen` string, date-time
        - `lastSeen` string, date-time
        - `transactionsPerDay` number, double
        - `peakHours` HourBucket[]
          - `hour` integer
          - `count` integer
      - `volumeStats` AssetVolumeStats[]
        - `asset` string
        - `totalVolume` union: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `averageVolume` union: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `minVolume` union: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `maxVolume` union: Arbitrary-precision unsigned BigUint value encoded as a JSON number by default, or a canonical decimal string when Formance-Bigint-As-String is enabled. The same rule applies to every response BigUint value, including nested fields, regardless of business meaning. JavaScript consumers should enable the header to avoid number rounding.
          - integer
          - string
        - `transactionCount` integer
      - `metadataKeys` string[]
    - `totalTransactions` integer
    - `totalReverted` integer

## 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 `analyzeTransactions` removed and replaced with `v3AnalyzeTransactions`
- **2026-10-09** `0ed18e459f51`: 4 breaking, 1 info
  - response property `data/flowPatterns/items/volumeStats/items/averageVolume` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/flowPatterns/items/volumeStats/items/maxVolume` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/flowPatterns/items/volumeStats/items/minVolume` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - response property `data/flowPatterns/items/volumeStats/items/totalVolume` list-of-types was widened by adding types `integer` to media type `application/json` of response `200`
  - …1 more
- **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-09-30** `b747efd5cd77`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/analyze-transactions/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)