Item Metrics API

• Overview
• General workflow
• Submit Report Endpoint (asynchronous)
• View Report Endpoint (synchronous)
• Sample reference reports

Overview

General workflow

1. Report Filters: You set filters like ReportName, CaptureDateStart/End, MessageTypes, Departments, and whether to ReturnByMonitoredEmployee.
2. ReturnByMonitoredEmployee Behavior:
   • ReturnByMonitoredEmployee = False (Default)
     • Dates are filtered by Capture Date.
     • Data is grouped by Department.
     • Current day’s data is excluded.
     • Output → Counts per Department.
   • ReturnByMonitoredEmployee = True
     • Dates are filtered by Capture Date.
     • Data is grouped by Monitored Employee.
     • Employee IDs are included.
     • Output → Counts per Employee.
   Notes:
   • Date always refers to Capture Date.
   • The grouping changes depending on whether you return by employee or not.

Submit Report Endpoint (asynchronous)

1. Call the Item Metrics Async API to submit a report generation request.
   This asynchronous API supports GET and POST query methods. Use any of the following as needed:
   • GET https://<Reporting endpoint base URL>/OData/ ItemMetricsAsync?ReportName=<Name of the report>&CaptureDateStart=<YYYY-MM-DD>& CaptureDateEnd=<YYYY-MM-DD>
   • POST https://<Reporting endpoint base URL>/OData/ ItemMetricsAsync
   Sample Requests
   • GET https://<Reporting endpoint Base URL>/odata/ ItemMetricsAsync?CaptureDateStart=2025-12-01&CaptureDateEnd=2025-12-31&ReportName=TestItemMetrics
   • POST https://<Reporting endpoint base URL>/OData/ItemMetricsAsync
   Parameter/Filters
   The following parameters/filters can be used with the Item Metrics Async API when invoked using the GET and POST methods. The system uses the AND operator between the filters to return the result based on the specified filters.

   Parameter	Required	Description
   ReportName	Mandatory	Specify the name of the report you want to generate.
   		Data Type: String
   		Limitations
   		- The report name can be up to a maximum of 256 characters long.
   		- Special characters are not allowed; only alphanumeric values are permitted.
   CaptureDateStart	Mandatory	CaptureDate refers to the date on which items are captured or ingested in Arctera Surveillance is recorded as the CaptureDate for that item.
   		This filter specifies the start date for returning count of items whose CaptureDate is greater than or equal to this start date.
   		Data Type: Date in the YYYY-MM-DD format.
   		Limitations
   CaptureDateEnd	Mandatory	CaptureDateEnd refers to the end date for returning count of items whose CaptureDate is less than or equal to this date.
   		Data Type: Date in the YYYY-MM-DD format.
   		Limitations
   Departments	Optional	Specifies the departments to which the item belongs and returns item counts for items within that department.
   		Data Type: JSON array of integers id (identifier fields) that is Department IDs.
   		Limitation
   		As an input, this API can pass maximum of 1000 Departments IDs.
   		- To include results for all departments of a specified customer in a report, do not specify any department IDs in a query.
   		- To include results for specific departments of a specified customer in a report, specify department IDs in the query.
   		Note: To get the Department IDs, See Departments API. Refer to the departmentId field only.
   MessageTypes	Optional	Specifies the type of captured items and returns item counts for items that have the specified message type.
   		Data Type: JSON array of integers 'id' (identifier fields) that is MessageTypes IDs.
   		Limitation
   		As an input, the Item Metrics API can pass maximum 100 MessageTypes IDs on a single page.
   ReturnBy MonitoredEmployee	Optional	Specifies whether report results are grouped by monitored employees. This parameter value is set to false by default.
   		- When set to false or not specified, it returns the item metrics count grouped by departments. Note: When report results are grouped by departments, results are returned only up to the previous day. Results for the current date are not included.
   		- When set to true, it returns the item metrics count grouped by monitored employees. The monitoredEmployeeId and monitoredEmployee parameters are applicable, and return the corresponding values in the response.
   		Data Type: Boolean
   		Possible values: true, false

   Note: If no optional parameters are specified (such as in the GET request), the Item Metrics API returns counts for all Departments and MessageTypes.
   Scenario 1: A new request to submit the report
   Sample request:
   
   Sample response:
   
   Note: The API response for Item Details, Item Metrics, and Evidence of Review reports also include the input parameters specified during report generation as shown in the image below.
   
   Refer to the table below for details on the attributes included in the ItemMetricsAsync API response.

   Name	Description
   reportId	Displays report ID. It is generated upon successful execution of API.
   reportName	Displays report name. It is generated upon successful execution of API.
   reportType	Displays the report type as Item Metrics.
   reportDate	Displays the date of report generation after successful execution of API.
   reportStatus	Displays report status. For more information on statuses, see Report Status API .
   info	Displays a message if the report request has queued successfully or not.
   newReportInstanceQueued	Specifies whether a new report generation request has been submitted or not. The Rate Limiting feature restricts submission of multiple requests with identical input parameters if attempted within one minute.
   	It returns the following values:
   	True: The value is shown as True, if the new report request has been queued successfully.
   	False: The value is shown as False, if the input parameters of the current request are identical to the parameters of the already submitted request within one minute, a new report will not be queued. As a result, the details of the existing report request are returned.
   reportStatusLocation	Displays a URL with report ID.
   	To view the status of this report, use the same URL.
   reportDataLocation	Displays a URL for the location of report data.
   	To access the report data, use the same URL.

   Scenario 2: A new request to submit the report when ReportName parameter is ignored
   Sample request:
   
   Sample response:
   
   Scenario 3: A new request to submit the report when one of the dates parameter is ignored
   Sample request:
   
   Sample response:
   
2. Call the ReportStatus API to get the status of the Item Metrics Async API report. See Report Status API.
3. Once the report is ready, call the Item Metrics synchronous API to retrieve the report data from the asynchronous API.

View Report Endpoint (synchronous)

• GET https://<Reporting endpoint Base URL>/odata/ItemMetrics?reportid=<ID of the ItemMetricsAsync API report>

Sample reference reports