Skip to main content

# Report control

This section of the API allows you to manage reports that reflect the system's performance.

A report is created with a specified time interval for collecting metrics and then put into processing. Once processed, the metrics can be retrieved via the API.

You can view the status of the report in the “status” field. The possible report statuses are:

- 0: Pending – The report has just been created and processing has not started.
- 1: Processing – The report is being processed. The time to process may vary depending on the database size and the reporting period.
- 2: Completed – The report has been successfully processed. If the data for the check period has been updated, a new report must be created to retrieve it.
- 3: Error – An error occurred while generating the report.
- 4: Canceled – Report processing has been canceled. Resuming report processing will only affect metrics that were not calculated for the previous processing.
- 5: Unexpectedly stopped – Report generation was unexpectedly interrupted, such as if the service was restarted during report processing.

### Report Data​

The report consists of several sections.

#### Nist Section​

The section contains the following metrics:

- failRate. The percentage of applicants who have a status of "Fail" or "Failed Attempt" relative to the total number of applicants.
- passRate. The percentage of applicants who have a "Success" status relative to the total number of applicants.
- completion. The average time taken from the creation of an applicant to their registration.
- suspectedFraud. The percentage of attempts with risks relative to the total number of attempts.
- abandonmentRate. The percentage of applicants in a "Pending" status relative to the total number of applicants.
- fraudProofing. The total number of applicants who have been "Cancelled" combined with the number of registration attempts with risks.
- fraudAuthentication. The total number of applicants with a "Cancelled" status combined with the number of authentication attempts with risks.
- authenticationFailures. The average proportion of failed attempts relative to the total number of attempts for each applicant.

### RegistrationMetrics section​

The section contains the following metrics:

- applicantsAttemptToRegister. The number of applicants that have attempted to register or have registered, i.e. have at least one attempt.

The section contains the following subsections:

- registeredApplicantsSettledInRegAttempts. Applicants who successfully registered within the allowed number of attempts.
- registeredApplicantsNotSettledInRegAttempts. Applicants who registered but exceeded the allowed attempts. If unlimited attempts are enabled, this data will be labeled “Not calculated due to system settings”.
- notRegisteredApplicantsSettledInRegAttempts. Applicants who failed to register but stayed within the allowed attempt limit.
- notRegisteredApplicantsNotSettledInRegAttempts Applicants who failed to register and exceeded the allowed attempts. If unlimited attempts are enabled, this data will be labeled “Not calculated due to system settings”.

All subsections above contain the same metrics. A dot notation indicates nested values (e.g., sample.data means the data key exists inside the sample dictionary). List of metrics:

- count. Number of applicants in a category.
- failReasons.validationFailuresCount.qualityFailedSum. Number of quality check failures.
- failReasons.validationFailuresCount.faceMatchingFailedSum. Number of face matching failures during registration.
- failReasons.validationFailuresCount.deepfakeFailedSum. Number of DeepFake check failures at registration.
- failReasons.validationFailuresCount.lrCrossMatchFailedSum. Number of frame matching failures from video Liveness Reflection.
- failReasons.validationFailuresCount.mcCrossMatchFailedSum. Number of frame matching failures from Motion Control video.
- failReasons.validationFailuresCount.oneFrameLivenessFailedSum. Number of one frame liveness check failures.
- failReasons.validationFailuresCount.livenessReflectionFailedSum. Number of Liveness Reflection failures.
- failReasons.inactiveRisksCount.massAttackRiskCount. Number of inactive MassAttack risk triggers.
- failReasons.inactiveRisksCount.duplicateFaceCount. Number of inactive DuplicateFace risk triggers.
- failReasons.inactiveRisksCount.periodicAttackCount. Number of inactive PeriodicAttack risk triggers.
- failReasons.inactiveRisksCount.missingMetadataCount. Number of inactive MissingMetadata risk triggers.
- failReasons.inactiveRisksCount.untrustedIpCount.Number of inactive UntrustedIp risk triggers.
- failReasons.inactiveRisksCount.untrustedDeviceCount. Number of inactive UntrustedDevice risk triggers.
- failReasons.inactiveRisksCount.inconsistentMetadataCount. Number of inactive InconsistentMetadata risk triggers.
- failReasons.inactiveRisksCount.motionControlFailedCount. Number of inactive MotionControlFailed risk triggers.
- failReasons.activeRisksCount.massAttackRiskCount. Number of active MassAttack risk triggers.
- failReasons.activeRisksCount.duplicateFaceCount. Number of active DuplicateFace risk triggers.
- failReasons.activeRisksCount.periodicAttackCount. Number of active PeriodicAttack risk triggers.
- failReasons.activeRisksCount.missingMetadataCount. Number of active MissingMetadata risk triggers.
- failReasons.activeRisksCount.untrustedIpCount.Number of active UntrustedIp risk triggers.
- failReasons.activeRisksCount.untrustedDeviceCount. Number of active UntrustedDevice risk triggers.
- failReasons.activeRisksCount.inconsistentMetadataCount. Number of active InconsistentMetadata risk triggers.
- failReasons.activeRisksCount.motionControlFailedCount. Number of active MotionControlFailed risk triggers.

### Create a report​

When creating a report, specify the time period for receiving metrics. The time must be specified in the UTC time zone.

Endpoint: POST /publicapi/api/v2/private/Report

Request body:

    {
      "startDate": "2024-11-19T11:09:44.530Z",
      "endDate": "2024-11-19T11:09:44.530Z"
    }

Request example:

    curl -X 'POST' \
      'http:/baf.ai/publicapi/api/v2/private/Report' \
      -H 'accept: text/plain' \
      -H 'Content-Type: application/json-patch+json' \
      -d '{
      "startDate": "2024-11-19T11:09:44.530Z",
      "endDate": "2024-11-19T11:09:44.530Z"
    }'

Response example:

Status Code | 200

    {
      "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
      "reportInfo": {
        "nist": {
          "failRate": 0.5,
          "passRate": 0.5,
          "completion": 401,
          "fraudProofing": 0,
          "suspectedFraud": 0,
          "abandonmentRate": 0,
          "fraudAuthentication": 0,
          "authenticationFailures": 0.6666667
        },
        "registrationMetrics": {
          "applicantsAttemptToRegister": 2,
          "notRegisteredApplicantsSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "notRegisteredApplicantsNotSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 3,
                "mcCrossMatchFailedSum": 2,
                "oneFrameLivenessFailedSum": 3,
                "livenessReflectionFailedSum": 1
              }
            }
          },
          "registeredApplicantsSettledInRegAttempts": {
            "count": 1,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          },
          "registeredApplicantsNotSettledInRegAttempts": {
            "count": 0,
            "failReasons": {
              "inactiveRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "activeRisksCount": {
                "massAttackRiskCount": 0,
                "untrustedIpRiskCount": 0,
                "duplicateFaceRiskCount": 0,
                "periodicAttackRiskCount": 0,
                "missingMetadataRiskCount": 0,
                "untrustedDeviceRiskCount": 0,
                "inconsistentMetadataRiskCount": 0,
                "motionControlFailedRiskCount": 0
              },
              "validationFailuresCount": {
                "qualityFailedSum": 0,
                "faceMatchingFailedSum": 0,
                "lrCrossMatchFailedSum": 0,
                "mcCrossMatchFailedSum": 0,
                "oneFrameLivenessFailedSum": 0,
                "livenessReflectionFailedSum": 0
              }
            }
          }
        }
      },
      "status": 2,
      "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
      "startDate": "2025-01-31T19:00:00Z",
      "endDate": "2025-02-08T18:59:59Z",
      "creationDate": "2025-02-04T08:26:26.774871Z",
      "lastModified": "2025-02-04T08:26:26.922604Z"
    }

### Receiving reports​

To receive reports page by page, you need to specify the page number and page size.

Endpoint: GET /publicapi/api/v2/private/Report

Parameters:

Field name | Description | Value
Page | Page number | From 1 to 2147483647
PageSize | Maximum number of reports listed on the page | From 1 to 400

Request example:

    curl -X 'GET' \
      'http:/baf.ai/publicapi/api/v2/private/Report?Page=1&PageSize=10' \
      -H 'accept: text/plain' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code | 200

    {
      "totalCount": 2,
      "reports": [
        {
          "id": "a86b6b35-cf6b-462d-9f64-d706cd2490ce",
          "reportInfo": null,
          "status": 0,
          "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
          "startDate": "2024-11-15T06:27:42.706Z",
          "endDate": "2024-11-15T06:27:42.706Z",
          "creationDate": "2024-11-15T06:27:42.231705Z",
          "lastModified": "2024-11-15T06:27:42.231705Z"
        },
        {
          "id": "d7b79e25-40e1-4aaa-a203-7ea77f5b6ef2",
          "reportInfo": {
            "nist": {
              "failRate": 0.5,
              "passRate": 0.5,
              "completion": 401,
              "fraudProofing": 0,
              "suspectedFraud": 0,
              "abandonmentRate": 0,
              "fraudAuthentication": 0,
              "authenticationFailures": 0.6666667
            },
            "registrationMetrics": {
              "applicantsAttemptToRegister": 2,
              "notRegisteredApplicantsSettledInRegAttempts": {
                "count": 0,
                "failReasons": {
                  "inactiveRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "activeRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "validationFailuresCount": {
                    "qualityFailedSum": 0,
                    "faceMatchingFailedSum": 0,
                    "lrCrossMatchFailedSum": 0,
                    "mcCrossMatchFailedSum": 0,
                    "oneFrameLivenessFailedSum": 0,
                    "livenessReflectionFailedSum": 0
                  }
                }
              },
              "notRegisteredApplicantsNotSettledInRegAttempts": {
                "count": 1,
                "failReasons": {
                  "inactiveRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "activeRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "validationFailuresCount": {
                    "qualityFailedSum": 0,
                    "faceMatchingFailedSum": 0,
                    "lrCrossMatchFailedSum": 3,
                    "mcCrossMatchFailedSum": 2,
                    "oneFrameLivenessFailedSum": 3,
                    "livenessReflectionFailedSum": 1
                  }
                }
              },
              "registeredApplicantsSettledInRegAttempts": {
                "count": 1,
                "failReasons": {
                  "inactiveRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "activeRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "validationFailuresCount": {
                    "qualityFailedSum": 0,
                    "faceMatchingFailedSum": 0,
                    "lrCrossMatchFailedSum": 0,
                    "mcCrossMatchFailedSum": 0,
                    "oneFrameLivenessFailedSum": 0,
                    "livenessReflectionFailedSum": 0
                  }
                }
              },
              "registeredApplicantsNotSettledInRegAttempts": {
                "count": 0,
                "failReasons": {
                  "inactiveRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "activeRisksCount": {
                    "massAttackRiskCount": 0,
                    "untrustedIpRiskCount": 0,
                    "duplicateFaceRiskCount": 0,
                    "periodicAttackRiskCount": 0,
                    "missingMetadataRiskCount": 0,
                    "untrustedDeviceRiskCount": 0,
                    "inconsistentMetadataRiskCount": 0,
                    "motionControlFailedRiskCount": 0
                  },
                  "validationFailuresCount": {
                    "qualityFailedSum": 0,
                    "faceMatchingFailedSum": 0,
                    "lrCrossMatchFailedSum": 0,
                    "mcCrossMatchFailedSum": 0,
                    "oneFrameLivenessFailedSum": 0,
                    "livenessReflectionFailedSum": 0
                  }
                }
              }
            }
          },
          "status": 2,
          "accountId": "28608d66-a571-44ec-94db-04a00143ff51",
          "startDate": "2025-01-31T19:00:00Z",
          "endDate": "2025-02-08T18:59:59Z",
          "creationDate": "2025-02-04T08:26:26.774871Z",
          "lastModified": "2025-02-04T08:26:26.922604Z"
        }
      ]
    }

### Deleting a report​

Endpoint: DELETE /publicapi/api/v2/private/Report

Request example:

    curl -X 'DELETE' \
      'http:/baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
      -H 'accept: */*' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code | 200

Possible errors:

HTTP Code | Message | Description | Error code
404 | Report not found | Report not found for deletion. | 120024

### Receiving report data in csv format​

Endpoint: GET /publicapi/api/v2/private/Report/{report_id}/Data

Request example:

    curl -X 'GET' \
      'http:/baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6/Data' \
      -H 'accept: */*' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'curl -X 'GET'

Response example:

Status Code | 200

Possible errors:

HTTP Code | Message | Description | Error code
404 | Report not found | Report not found. | 120024

### Receiving report information​

Endpoint: GET /publicapi/api/v2/private/Report/{report_id}

Request example:

    curl -X 'GET' \
      'http:/baf.ai/publicapi/api/v2/private/Report/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
      -H 'accept: text/plain' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'curl -X 'GET'

Response example:

Status Code | 200

Possible errors:

HTTP Code | Message | Description | Error code
404 | Report not found | Report not found. | 120024

### Starting building a report​

Endpoint: GET /publicapi/api/v2/private/Report/process/{report_id}

Request example:

    curl -X 'POST' \
      'http:/baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
      -H 'accept: */*' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a' \
      -d ''

Response example:

Status Code | 200

Possible errors:

HTTP Code | Message | Description | Error code
404 | Report not found | Report not found. | 120024
400 | Report already processing | Report already processing | 120024
400 | Too many simultaneously processed reports | The number of simultaneously processed reports has reached the limit. | 120024

### Canceling report generation​

Endpoint: DELETE /publicapi/api/v2/private/Report/process/{report_id}

Request example:

    curl -X 'DELETE' \
      'http:/baf.ai/publicapi/api/v2/private/Report/Process/3fa85f64-5717-4562-b3fc-2c963f66afa7' \
      -H 'accept: */*' \
      -H 'Authorization: Bearer sk_1d2ca11d-125a-416c-8fdc-e9661ebecb9a'

Response example:

Status Code | 200

Possible errors:

HTTP Code | Message | Description | Error code
400 | This report not processing at this moment | The report is not in the processing state | 120024