How do I run an advanced reconciliation and monitor its results?

You can run a reconciliation definition to compare the data on each side.

Each time you run a reconciliation definition, LUSID creates an instance. If you then fix data and rerun it, LUSID reruns the same instance rather than creating a new one. An instance is therefore a run of a reconciliation definition, including any reruns.

Recommended reading: Understanding advanced reconciliations, Understanding result sets in advanced reconciliations

Prerequisites

Before you start, make sure you've created a reconciliation definition.

Running a reconciliation

curl -X POST "https://<your-domain>.lusid.com/api/api/recs/instances"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "recDefinitionId": {
    "scope": "Finbourne-Examples",
    "code": "HoldingUnitsReconciliation"
  },
  "leftEffectiveAt": "2026-10-01T00:00:00.0000000+00:00",
  "rightEffectiveAt": "2026-10-01T00:00:00.0000000+00:00"
}"

Choosing dates

For each side, you choose an effective date. LUSID reconciles each side's data effective at that date. If you don't choose a date, the instance defaults to the time you run the reconciliation.

Which dates you can choose depends on the reconciliation definition’s date policy:

• Series: Both effective dates must be later than the previous instance's.

• Unconstrained: You can choose any effective dates.

• Explicit as at dates: You also choose the as at date for that side. LUSID uses the data as it was known at that time.

• Contiguous activity window: Each instance covers the activity since the previous instance's effective date. Note you don’t choose a window.

Monitoring runs

Using the web app

Navigate to Advanced Recs > Overview to see the status of your instances, their result sets, and any reruns.

Each instance has an overall status:

On the Overview dashboard:

• The strip at the top of the page lists the reconciliations that are currently running.

• The dashboard doesn’t refresh automatically when a run finishes. Click the Refresh icon to update it.
  

• Each reconciliation type shows its current run, for example Run 2, and whether it succeeded or failed. Click the dropdown arrow next to a reconciliation type to see its previous runs.
  

• Click the View result set icon to open a reconciliation type’s results. This always opens the latest run.
  

Using the LUSID API

Call the GetRecInstance API at intervals until the instance’s status is no longer Running. If a reconciliation type failed, its result set’s execution.errorDetail gives the reason.

For the status of each result set and result, see Understanding result sets in advanced reconciliations.

Rerunning an instance

Rerun an instance after you fix the data behind an exception, or after a run fails. A rerun reconciles the same effective dates again, and carries forward comments, assignments, and review decisions. See Understanding results in advanced reconciliations.

A rerun doesn't create a new instance. It keeps the instance's effective dates and activity window, and:

• A side with Latest as at dates picks up the latest version of the data, including your corrections.

• A side with Explicit as at dates stays fixed.

• Uses the reconciliation definition and matching rulesets as they were when the instance was created. To use changes you’ve made since, run the reconciliation definition again. This creates a new instance.

You can't rerun an instance if:

• Both sides use Explicit as at dates, because nothing would change.

• The instance is locked.

You can rerun an earlier instance in a series without affecting the instances after it.

Methods

You can currently only rerun an instance using the LUSID API.

Note

You can follow the rerun and review its results in the Overview dashboard in the LUSID web app.

Call the TransitionRecInstance API with the instance ID in the URL and action set to ReRun, for example:

curl -X POST "https://<your-domain>.lusid.com/api/api/recs/instances/Manual/3f2b6c1e-8d4a-4c7b-9e2f-1a5d6b7c8e9f/$transition"
  -H "Authorization: Bearer <your-API-access-token>"
  -d "{
  "action": "ReRun"
}"

To unlock a locked instance first, call the same API with the action Unlock.

What happens after rerunning

LUSID starts the rerun and responds straight away, with the instance’s status set to Running. While the instance is Running, you can add comments to results, but you can’t review results, or submit or approve result sets.

When the rerun finishes, each reconciliation type has a new result set, with a run number incremented by one. The new result sets start at Under review, so you need to review and approve them again.