Reconciliation
The Reconciliation screen lets you import the billing export of a provider, run the reconciliation that writes
the billed cost on the usage events, and read the variance report of a month. Portal path: /finops/reconciliation
(menu FinOps > Reconciliation). FinOps analysts and tenant administrators import and run; auditors read the
report.
What the screen shows
The screen has two tabs: Variance report (default) and Imports (/finops/reconciliation?tab=imports).
| Area | Content |
|---|---|
| Import a provider export (FinOps administrators only) | Source (OpenAI, Anthropic, AWS CUR, Azure, Google Cloud, Generic CSV), Period (month, the current month by default), Export file (.csv or .json), and the Import and Run reconciliation buttons. |
| Variance report cards | Estimated, Measured, Billed, Imported, Unmatched totals of the month in the tenant currency, and Variance %. |
| Variance report table | One row per provider, model and day: Provider, Model id, Day, Events, Estimated, Measured, Billed, Variance %, Over threshold. |
| Raw response | Expandable JSON of the report, including the variance alerts (alert_items). |
| Imports tab | Source, Provider, File, Lines, Total, Period start, Period end, Created. |
| Empty states | No reconciliation yet (import an export file and run the reconciliation); No import. |
A billed line that carries the provider request id goes to that usage event; the other lines are shared pro rata of the measured cost between the events of the same provider, model and day. Lines without a matching event are counted as Unmatched.
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Import (enabled once a file is chosen) | Reads the file in the browser and sends its content with the source and the file name. Shows Export imported, then reloads the imports and the report. | POST /v1/finops/reconciliation/imports | finops, tenant_admin, platform_admin |
| Run reconciliation | Matches the imported lines with the usage events of the month chosen in Period, then reloads the report. Also offered in the empty state. | POST /v1/finops/reconciliation/run (from, to of the month) | finops, tenant_admin, platform_admin |
| Period | Changes the month of the report. | GET /v1/finops/reconciliation/report (from, to) | finops, tenant_admin, platform_admin |
| Retry (error panel) | Reloads the report. | GET /v1/finops/reconciliation/report | Readers of the FinOps section |
| Refresh (round arrow icon, Imports tab) | Reloads the imports. | GET /v1/finops/reconciliation/imports | Readers of the FinOps section |
Roles
| Role | Access |
|---|---|
finops, tenant_admin | Import, run and read (ADMIN_ROLES of services/control-plane/src/eai/domains/finops/__init__.py). |
platform_admin | Same rights, inside a tenant (tenant_required otherwise). |
auditor | Reads the report and the imports. The import section, with its Period field, is hidden: the report shows the current month. |
developer, viewer, security_officer | Allowed to read by the API, but the FinOps section of the portal menu does not open for them. |
Typical tasks
Reconcile the invoice of last month
- Get the provider export. Download the billing export of the month from the provider console (CSV or JSON).
Expected result: you have a file such as
<export-file>.csv. If it fails: for a provider not listed in Source, use Generic CSV. - Choose the source and the month. Select the provider in Source and the month in Period.
Expected result: the report below shows the month chosen.
If it fails: if the import section is missing, ask for the
finopsrole. - Import the file. Choose it in Export file and click Import.
Expected result: Export imported appears and the Imports tab lists the file with its line count.
If it fails:
import_invalidgives the reason why the file could not be read; check the source chosen. - Run the reconciliation. Click Run reconciliation so the billed lines are written on the usage events.
Expected result: the cards and the table show the Billed cost and the Variance %.
If it fails: an error
fx_rate_missingmeans an exchange rate is missing; load it in FinOps settings.
Investigate a variance
- Find the rows over threshold. Rows with Over threshold set exceed the variance threshold of the tenant. Expected result: you know the provider, model and day concerned. If it fails: if no row is flagged, the threshold may be too high; check it in FinOps settings.
- Look at the events of that day. Open Usage events filtered on the model and the day. Expected result: you see the measured and billed cost of each call. If it fails: check the Unmatched card: billed lines without an event point to calls the gateway did not report.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Error import_invalid (HTTP 422): "The provider export could not be read: ..." | The file does not match the format of the source chosen. | Choose the right Source, or Generic CSV. |
Error fx_rate_missing (HTTP 422): "No exchange rate from ... to ... is available at ..." | The export currency differs from the tenant currency and no rate covers the date. | Load the rate in the Exchange rates tab of FinOps settings. |
Error validation_error (HTTP 422) | The period start is after its end (API calls). | Choose a valid month. |
| Import stays disabled | No file chosen. | Choose a .csv or .json file. |
| High Unmatched total | Billed lines with no usage event of the same provider, model and day. | Check that the gateway reports usage for every call. |
Error forbidden (HTTP 403) on import or run | Not a FinOps administrator. | Ask for the finops role. |