> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/guides/administrator-guide/automated-usage-reporting.md).

# Automated Usage Reporting

Starting with API 6.6.4, you can use new functionality: automated billing reconciliation. Previously, monthly usage reconciliation for billing purposes was semi-automatic and required manual steps on both sides. The new version automates this process: the API sends usage counters directly to Cryptlex, removing the manual reconciliation steps and making monthly billing more accurate and more transparent for both you and us. Cryptlex is a third-party service that we have already been utilizing to manage licenses for our on-premise clients for several years. Now, this service additionally helps count transactions, where a transaction is a folder that reached a final result, SUCCESS or DECLINED. Face Matching, Liveness and Collection analyses are counted as well.

{% hint style="info" %}
The functionality applies to on-premise deployments with a cloud-connected license.
{% endhint %}

#### What you get

* **No manual reconciliation:** monthly usage reconciliation for billing runs automatically, with no manual steps on your side.
* **Billing in business units:** usage is counted in completed verifications.
* **Transparency:** `Transaction`, `FaceMatching`, `Liveness` and `Collection` are reported separately, each broken down by result status.
* **Fewer discrepancies:** you and Oz rely on the same automatically collected figures, with less back-and-forth over invoices.

#### How usage is counted

Oz API sends totals only, never details of single transactions (who, when, or what result).

* There are four dimensions: `Transaction`, `FaceMatching`, `Liveness` and `Collection` (1:N). Each is sent as a total plus `<dimension>_SUCCESS`, `<dimension>_DECLINED` and `<dimension>_FAILED_INFO`, 16 counters in all.
* `Transaction` is counted once per folder: for the first request after which the folder is in SUCCESS or DECLINED. Further requests to the same folder don't add a `Transaction`, but their analyses are still billed. In Instant API, each request is a separate folder, so `Transaction` equals the number of requests.
* Each analysis is counted by its own status, regardless of the folder status.
* The total includes SUCCESS and DECLINED. FAILED is sent to `<dimension>_FAILED_INFO` for reference only: it is not billed and not included in the total. OPERATOR\_REQUIRED and not yet completed analyses are not sent at all.
* If your contract bills only SUCCESS results, usage is calculated by `<dimension>_SUCCESS`.
* Counters build up in the API container and are sent as totals, at most once an hour per counter.
* Reporting is not real-time: consumption is calculated over the billing period.

{% hint style="warning" %}
Counting changed in Oz API 6.9.0, so figures before and after the upgrade to 6.9.0 are not comparable:

* In multi-step scenarios, `Transaction` will be noticeably lower.
* A FAILED analysis is no longer included in the total, even in a folder with SUCCESS.
* The status breakdown and `Collection` are counted only from the upgrade. Data already sent is not recalculated.
  {% endhint %}

#### What data is sent

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Sent</th><th>Not sent</th></tr></thead><tbody><tr><td>License key, Oz product and account IDs</td><td>Photos, videos, scanned documents</td></tr><tr><td>Machine identity: hashed fingerprint, hostname, hashed OS username</td><td>Face images, biometric templates or vectors</td></tr><tr><td>Platform: OS and version, container or not, hypervisor name</td><td>End-user names, document numbers, emails or other IDs</td></tr><tr><td>16 counters as integers: <code>Transaction</code>, <code>FaceMatching</code>, <code>Liveness</code>, <code>Collection</code>, each as a total and by status (<code>_SUCCESS</code>, <code>_DECLINED</code>, <code>_FAILED_INFO</code>)</td><td>Analysis inputs, results, scores, folder contents</td></tr><tr><td></td><td>Database records, logs, other configuration</td></tr><tr><td></td><td>End-user IPs, location, device info</td></tr><tr><td></td><td>Customer or tenant names, account structure</td></tr><tr><td></td><td>Free-form metadata (Oz leaves <code>metadata</code> and <code>customAttributes</code> empty)</td></tr></tbody></table>

#### What you need to do

1. If you upgrade to **6.9.0 or higher**, do it only after we have updated your license. If the license lacks any of the 16 counters (meter attributes), analyses are rejected with HTTP 500, `error_code` 11.
2. Upgrade Oz API to **6.6.4 or higher** (Kubernetes: Helm chart **0.20.33 or higher**).
3. Allow outbound HTTPS (port 443) from the API container to the Cryptlex domain for your region (see Network access).

{% hint style="warning" %}
The upgrade alone doesn't open access. The firewall rule is needed even if you already run 6.6.4 or higher.
{% endhint %}

Everything else is on our side: we set up your license in Cryptlex, configure the API, and confirm that data is arriving.

**To check the result:** in Oz API 6.6.4 and higher, call `GET /api/healthcheck/`. It should return a `license` section with status `ok` when the license is active, or an error if it is invalid or revoked.

#### If service is unavailable

An activated license keeps working for a grace period, and counters not yet sent are stored locally.

* **No connection at first start:** there is no grace period yet. Analyses are rejected with HTTP 500, `error_code` 11, until the license is activated.
* **Connection lost:** an activated license keeps working for a grace period while the API reconnects in the background. Counters are stored locally and sent when the connection returns, with no action needed. The grace period length is set in your license; we can share it on request.
* **Grace period over, still no connection:** analysis requests are rejected until the license is validated again. Other requests still work.
* **Cryptlex back after an outage:** everything recovers without a restart. Retries run with pauses of 5, 10 and 20 minutes, so counters arrive with a delay.
* **License revoked:** the grace period doesn't apply, and analyses stop. After the license is restored, the API container must be restarted.

{% hint style="warning" %}
No usage data is lost if the cache directory (`OZ_APP_CACHE_DIR`) is on a persistent volume. Otherwise, counters not yet sent are lost when the container or pod is re-created.
{% endhint %}

Under its [Service Level Agreement](https://cryptlex.com/legal/service-level-agreement), Cryptlex commits to at least 99.9% monthly uptime for its Web API and portals.

#### For security and infrastructure teams

**Network access**

One outbound HTTPS connection: from the Oz API container to `api.cryptlex.com` (or `api.eu.cryptlex.com`, depending on your region), port 443. No inbound connections, no other recipients.

The destination isn't new: the BIO container already connects to the same domain over the same port.

**API calls**

The calls are made by the Cryptlex SDK inside the API container. The exact pattern may change between SDK versions.

| Method                                                                                                                        | Purpose                                                                   | Frequency         |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------- |
| [`POST /v3/activations`](https://cryptlex.com/reference/web-api/post-activations)                                             | Activates the license at container start, or reclaims a lost license slot | A few per restart |
| [`PATCH /v3/activations/{id}`](https://cryptlex.com/reference/web-api/patch-activations-id)                                   | Background license check                                                  | A few per hour    |
| [`POST /v3/activations/{id}/deactivate`](https://cryptlex.com/reference/web-api/post-activations-id-deactivate)               | Releases the license on shutdown                                          | Once per shutdown |
| [`POST /v3/activations/meter-attributes/{name}`](https://cryptlex.com/reference/web-api/post-activations-meter-attributes-id) | Sends a counter (one of 16)                                               | Up to 16 per hour |

Total: fewer than 60 requests per hour per API container, about 1 KB each.

**How to verify what is sent**

* **Specification:** every call is in Cryptlex's public API reference (links in the table above). Request fields are strings, integers or booleans (some grouped into lists), with no fields for files or binary data. For example, the counter request contains only an `increment` number and the `activationId`, `accountId` and `productId` identifiers.
* **Traffic:** monitor outbound volume on your proxy or NGFW and compare it with the normal volume above.
* **Egress:** allow the API container to reach only the Cryptlex domain on port 443.

**Monitoring**

* A worker may restart itself (SIGTERM, no earlier than 15 minutes after start). This is expected.
* Log lines to monitor:
  * `CRYPTLEX integration: … failed`
  * `… connection restored`
  * `restarting the leader worker`
* `GET /api/healthcheck/` returns the `grace_period` flag.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/administrator-guide/automated-usage-reporting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
