Skip to main content

List reconciliations

This recipe shows how to list reconciliation runs in your tenant. A reconciliation run is a single execution of the match engine against one or more account pairs.

Endpoint​

GET /v1/reconciliations

Returns an array of reconciliation runs with the run UUID, run type (live or scheduled), accounts involved, status, match rate, exception count, and run duration.

Prerequisites​

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

Request​

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

Response​

{
  "items": [
    {
      "id": "rec-001",
      "tenant_id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
      "run_type": "scheduled",
      "account_ids": ["acc-001", "acc-002"],
      "status": "completed",
      "started_at": "2026-08-22T03:00:00Z",
      "completed_at": "2026-08-22T03:04:23Z",
      "duration_seconds": 263,
      "match_rate": 0.984,
      "auto_matched_count": 12345,
      "analyst_review_count": 87,
      "exception_count": 112,
      "triggered_by": "cron"
    },
    {
      "id": "rec-002",
      "tenant_id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
      "run_type": "live",
      "account_ids": ["acc-001", "acc-002"],
      "status": "running",
      "started_at": "2026-08-22T14:23:11Z",
      "match_rate": null,
      "triggered_by": "user:alice"
    }
  ],
  "next_cursor": null
}

Filter parameters​

ParameterTypeDescription
limitinteger (1-200, default 50)Maximum runs to return
cursorstringPagination cursor
fromDateISO 8601 dateFilter runs started on or after this date
toDateISO 8601 dateFilter runs started on or before this date
statusstringrunning, completed, failed, cancelled
run_typestringlive, scheduled, manual
min_match_ratenumber (0-1)Minimum match rate threshold

Use cases​

  • Reconciliation dashboard — show recent runs with match rates.
  • SLA monitoring — flag runs that took longer than the SLA.
  • Audit trail — list all runs for periodic compliance review.

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 runs = await fvi.reconciliations.list({
  fromDate: '2026-08-01',
  toDate: '2026-08-22',
  limit: 100,
});

for (const run of runs.items) {
  console.log(`Run ${run.id} — match rate ${run.match_rate}`);
}

Python​

from falconveritas import FVI

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

runs = client.reconciliations.list(
  from_date="2026-08-01",
  to_date="2026-08-22",
  limit=100,
)
for run in runs.items:
  print(f"Run {run.id} — match rate {run.match_rate}")

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