Usage report
In order to obtain an overview of the Rossum usage, you can download Csv file with basic Rossum statistics.
The statistics contains following attributes:
- Username (may be empty in case document was not modified by any user)
- Workspace name
- Queue name
- User url
- Queue url
- Workspace url
- Imported: count of all documents that were imported during the time period
- Confirmed: count of all documents that were confirmed during the time period
- Rejected: count of all documents that were rejected during the time period
- Rejected automatically: count of all documents that were automatically rejected during the time period
- Rejected manually: count of all documents that were manually rejected during the time period
- Deleted: count of documents that were deleted during the time period
- Exported: count of documents that were successfully exported during the time period
- Net time: total time spent by a user validating the successfully exported documents
Example usage report request:
curl -H 'Authorization: Bearer db313f24f5738c8e04635e036ec8a45cdd6d6b03' \
'https://example.rossum.app/api/annotations/usage_report?from=2019-01-01&to=2019-01-31'Csv file (csv) may be downloaded from https://example.rossum.app/api/v1/annotations/usage_report?format=csv.
You may specify date range using from and to parameters (inclusive). If not
specified, a report for last 12 months is generated.
Please note that direct access to the API may require you to login using Rossum
credentials. User must have admin or manager role.
Request
POST /v1/annotations/usage_report
| Attribute | Type | Description |
|---|---|---|
| filter | object | Filters to be applied on documents used for the computation of usage report |
| filter.users | list[URL] | Filter documents modified by the specified users (not applied to imported_count) |
| filter.queues | list[URL] | Filter documents from the specified queues |
| filter.begin_date | datetime | Filter documents that has date (arrived_at for imported_count; deleted_at for deleted_count; rejected_at for rejected_count; or exported_at for the rest) greater than specified. |
| filter.end_date | datetime | Filter documents that has date (arrived_at for imported_count; deleted_at for deleted_count; rejected_at for rejected_count; or exported_at for the rest) lower than specified. |
| exported_on_time_threshold_s | float | Threshold (in seconds) under which are documents denoted as on_time. |
| group_by | list[string] | List of attributes by which the series is to be grouped. Possible values: user, workspace, queue, month, week, day. |
Example request body with filters:
{
"filter": {
"users": [
"https://example.rossum.app/api/v1/users/173"
],
"queues": [
"https://example.rossum.app/api/v1/queues/8199"
],
"begin_date": "2019-12-01",
"end_date": "2020-01-31"
},
"exported_on_time_threshold_s": 86400,
"group_by": [
"user",
"workspace",
"queue",
"month"
]
}Please note that direct access to the API may require you to login using Rossum
credentials. User must have admin or manager role.
Response
The response consists of two parts: totalsand series.
Status: 200
Example usage report response:
{
"series": [
{
"begin_date": "2019-12-01",
"end_date": "2020-01-01",
"queue": "https://example.rossum.app/api/v1/queues/8199",
"workspace": "https://example.rossum.app/api/v1/workspaces/7540",
"values": {
"imported_count": 2,
"confirmed_count": 6,
"rejected_count": 2,
"rejected_automatically_count": 1,
"rejected_manually_count": 1,
"deleted_count": null,
"exported_count": null,
"turnaround_avg_s": null,
"corrections_per_document_avg": null,
"exported_on_time_count": null,
"exported_late_count": null,
"time_per_document_avg_s": null,
"time_per_document_active_avg_s": null,
"time_and_corrections_per_field": []
}
},
{
"begin_date": "2020-01-01",
"end_date": "2020-02-01",
"queue": "https://example.rossum.app/api/v1/queues/8199",
"workspace": "https://example.rossum.app/api/v1/workspaces/7540",
"user": "https://example.rossum.app/api/v1/users/173",
"values": {
"imported_count": null,
"confirmed_count": 6,
"rejected_count": 3,
"rejected_automatically_count": 2,
"rejected_manually_count": 1,
"deleted_count": 2,
"exported_count": 2,
"turnaround_avg_s": 1341000,
"corrections_per_document_avg": 1.0,
"exported_on_time_count": 1,
"exported_late_count": 1,
"time_per_document_avg_s": 70.0,
"time_per_document_active_avg_s": 50.0,
"time_and_corrections_per_field": [
{
"schema_id": "date_due",
"label": "Date due",
"total_count": 1,
"corrected_ratio": 0.0,
"time_spent_avg_s": 0.0
},
...
]
}
},
...
],
"totals": {
"imported_count": 7,
"confirmed_count": 6,
"rejected_count": 5,
"rejected_automatically_count": 3,
"rejected_manually_count": 2,
"deleted_count": 2,
"exported_count": 3,
"turnaround_avg_s": 894000,
"corrections_per_document_avg": 1.0,
"exported_on_time_count": 2,
"exported_late_count": 1,
"time_per_document_avg_s": 70.0,
"time_per_document_active_avg_s": 50.0
}
}Totals
Totals contain summary information for the whole period (between begin_date and end_date).
| Attribute | Type | Description |
|---|---|---|
| imported_count | int | Count of documents that were uploaded to Rossum |
| confirmed_count | int | Count of documents that were confirmed |
| rejected_count | int | Count of documents that were rejected |
| rejected_automatically_count | int | Count of documents that were automatically rejected |
| rejected_manually_count | int | Count of documents that were manually rejected |
| deleted_count | int | Count of documents that were deleted |
| exported_count | int | Count of documents that were successfully exported |
| turnaround_avg_s | float | Average time (in seconds) that a document spends in Rossum (computed as time exported_at - arrived_at) |
| corrections_per_document_avg | float | Average count of corrections on documents |
| exported_on_time_count | int | Number of documents of which turnaround was under exported_on_time_threshold |
| exported_late_count | int | Number of documents of which turnaround was above exported_on_time_threshold |
| time_per_document_avg_s | float | Average time (in seconds) that users spent validating documents. Based on the time_spent_overall metric, see annotation processing duration |
| time_per_document_active_avg_s | float | Average active time (in seconds) that users spent validating documents. Based on the time_spent_active metric, see annotation processing duration |
Series
Series contain information grouped by fields defined in group_by.
The data (see above) are wrapped in values object,
and accompanied by the values of attributes that were used for grouping.
| Attribute | Type | Description |
|---|---|---|
| user | URL | User, who modified documents within the group |
| workspace | URL | Workspace, in which are the documents within the group |
| queue | URL | Queue, in which are the documents within the group |
| begin_date | date | Start date, of the documents within the group |
| end_date | date | Final date, of the documents within the group |
| values | object | Contains the data of totals and time_and_corrections_per_field list (for details see below). |
In addition to the totals data, series contain time_and_corrections_per_field list
that provides detailed data about statistics on each field.
Series details
The detail object contains statistics grouped per field (schema_id).
| Attribute | Type | Description |
|---|---|---|
| schema_id | string | Reference mapping of the data object to the schema tree |
| label | string | Label of the data object (taken from schema). |
| total_count | int | Number of data objects |
| corrected_ratio* | float [0;1] | Ratio of data objects that must have been corrected after automatic extraction. |
| time_spent_avg_s | float | Average time (in seconds) spent on validating the data objects |
*Corrected ratio is calculated based on human corrections. If any kind of automation (Hook, Webhook, etc) is ran on the datapoints, even after a human correction took a place, the corrected_ration will not be calculated -> Is set to 0.