Skip to main content

Volume analysis

This recipe shows how to measure reconciliation volume over time with daily, weekly, and monthly aggregations. Volume analysis helps you track business growth, plan capacity, and detect anomalous spikes or drops.

Endpoint​

GET /v1/reconciliations/volume

Returns a time-series summary of reconciliation volumes with the chosen granularity.

Prerequisites​

  • A valid tenantId and bearer JWT.
  • The user must have at least one of: tenant_admin, tenant_analyst, tenant_lead, tenant_viewer.

Request​

curl -X GET "https://api.falconveritas.com/v1/reconciliations/volume?fromDate=2026-08-01&toDate=2026-08-22&granularity=daily" \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json"

Response​

{
  "granularity": "daily",
  "from_date": "2026-08-01",
  "to_date": "2026-08-22",
  "total_count": 12450,
  "total_auto_matched": 11456,
  "total_analyst_review": 723,
  "total_exceptions": 271,
  "series": [
    {
      "date": "2026-08-01",
      "total_count": 542,
      "auto_matched_count": 510,
      "analyst_review_count": 24,
      "exception_count": 8,
      "auto_match_rate": 0.941
    },
    {
      "date": "2026-08-02",
      "total_count": 612,
      "auto_matched_count": 581,
      "analyst_review_count": 23,
      "exception_count": 8,
      "auto_match_rate": 0.949
    }
  ]
}

Granularity options​

GranularityDescription
hourlyHourly aggregation (recommended for real-time monitoring)
dailyDaily aggregation (default)
weeklyWeekly aggregation (ISO 8601 week)
monthlyMonthly aggregation (calendar month)

Filter parameters​

ParameterTypeDescription
granularitystringOne of the granularities above
accountIdstringFilter to a specific account
sourceIdstringFilter to a specific ingestion source
runTypestringFilter to live, scheduled, or manual runs
minAmountnumberFilter to reconciliations above a minimum amount

Anomaly detection​

Volume spikes or drops beyond 3 standard deviations from the rolling 30-day median are flagged in the response:

{
  "anomalies": [
    {
      "date": "2026-08-15",
      "expected_count": 580,
      "actual_count": 1240,
      "deviation_sigma": 4.2,
      "anomaly_type": "spike",
      "probable_cause": "month-end batch ingestion from SAP"
    }
  ]
}

Use cases​

  • Capacity planning — forecast infrastructure needs as transaction volume grows.
  • Anomaly detection — detect ingestion failures (drops) or batch spikes (spikes).
  • Business intelligence — track transaction volume trends for executive reporting.
  • SLA tracking — correlate volume spikes with SLA breaches.

Code samples​

TypeScript​

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const volume = await fvi.reconciliations.volume({
  fromDate: '2026-08-01',
  toDate: '2026-08-22',
  granularity: 'daily',
});

console.log(`Total: ${volume.total_count}, Auto-match rate: ${(volume.total_auto_matched / volume.total_count * 100).toFixed(1)}%`);

for (const anomaly of volume.anomalies ?? []) {
  console.log(`Anomaly: ${anomaly.date} ${anomaly.anomaly_type} (${anomaly.deviation_sigma}σ) — ${anomaly.probable_cause}`);
}

Python​

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

volume = client.reconciliations.volume(
  from_date="2026-08-01",
  to_date="2026-08-22",
  granularity="daily",
)
print(f"Total: {volume.total_count}, Auto-match rate: {volume.total_auto_matched / volume.total_count * 100:.1f}%")

for anomaly in volume.anomalies or []:
  print(f"Anomaly: {anomaly.date} {anomaly.anomaly_type} ({anomaly.deviation_sigma}σ) — {anomaly.probable_cause}")

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/reconciliations.ts.