Audit services in REST

The Audit services available through REST include multiple endpoints that you can use to programmatically revert, retrieve, and search Relativity audit records stored in Elasticsearch. These services support interactions with both instance-level and workspace-level audit records. The following services provide endpoints for this functionality:

Note: These APIs don't support working with audit records stored in an SQL Server database.

Sample use cases for the Audit services include building custom applications to perform the following tasks:

You can access the Audit API services through .NET interfaces. These interfaces support the same functionality as available through REST. For more information, see Audit APIs.

This page contains the following information:

Prerequisites for using the Audit services

To begin developing with the Audit services, complete the following prerequisites:

Guidelines for Audit services

Review the following guidelines for working with the Audit services.

Operations supported by the Audit services

The following table list operations that you can perform using the Audit services.

Service name Endpoints available for these operations
Audit Metrics Retrieve the total number and size of audits
Audit Revert Validate a revert operation for an audit action
Revert an audit
Mass revert a list of audits
Audit Pivot Query with Pivot on audit data
Reviewer Statistics Retrieve action counts for updated documents
Retrieve the usage time per reviewer
Retrieve size of the extracted text for reviewed documents
Retrieve an aggregation of user actions by hour
Retrieve choices reviewed by users
Retrieve a summary report of reviewer statistics
Audit Query Query for an audit record
Audit Object Manager UI Query on audit fields
Query for a specific audit object
Query with additional query options
Query on audit fields and return a smaller payload

Admin-level context

To work with audits at the admin-level context, set the {{workspaceID}} variable in the URL for an endpoint to -1. For example, the {{workspaceID}} variable in following URL is set to -1, so this endpoints retrieves number and size of the audits for a Relativity instance. See Retrieve the total number and size of audits.

<host>/Relativity.REST/api/relativity.audit.metrics/workspaces/-1/audit-metrics/

Query conditions

You can specify conditions for an audit query in the condition or rowCondition fields in a JSON request. Setting these fields is equivalent to using conditions and list filtering in the Relativity UI. For information about rendering audit details in the Relativity UI, see Audit on the RelativityOne Documentation site.

Audit Metrics service

The Audit Metrics service supports the retrieval of information about the number and size of the audits in a specific workspace.

Retrieve the total number and size of audits

You can retrieve the total count of all audits in a workspace, and the total size of the audits in bytes. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.metrics/workspaces/{{workspaceID}}/audit-metrics/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

The body of the request is empty.

The response contains the following fields:

{
  "Count": 1579490,
  "SizeInBytes": 813470096
}

Audit Revert service

The Audit Revert service supports reverting document update actions. It provides endpoints for reverting a single action or list of actions, and for verifying whether the revert operation can be performed on an action.

For example, you can use an endpoint on this service as a programmatic shortcut for reverting incorrect coding decisions.

Validate a revert operation for an audit action

To validate that an audit action can be reverted, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/revert/validate/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Revert an audit

To revert an audit action, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/revert/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Note: Before reverting an action, consider calling the ValidateRevertAuditAsync() method to verify that the revert operation can succeed.

Mass revert a list of audits

You can control the maximum number of Audits that can be reverted during a mass operation by updating the RevertMaxAuditCount instance setting. For more information, see Instance settings descriptions on the Relativity Documentation site.

Note: This endpoint validates that each action can be successfully reverted before performing this operation.

To revert a list of audit actions, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.revert/workspaces/{{workspaceID}}/audits/massrevert/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Audit Pivot service

The Audit Pivot service supports running pivot queries on audit data. You can query with the group by and pivot on operations for object type, action, username, and timestamp fields.

After the call returns the pivot results, you can render them as graphs and charts with third-party visualization tools. Pivot queries on audit records use the same query pattern as Relativity Pivot. For more information, see Pivot Manager service.

Query with Pivot on audit data

To query on audit pivot data, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.pivot/workspaces/{{workspaceID}}/pivot/

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Reviewer Statistics service

The Reviewer Statistics service provides endpoints for returning information about reviewer actions, such as the number of action performed by a reviewer on a document, the usage time per review, a summary report of reviewer actions, and others.

See the following subsections for more information:

Retrieve action counts for updated documents

You can retrieve the total action counts for all the updated documents in a workspace for a specified time frame. Additionally, you can list specific actions that you want counted per document. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/document-action-counts/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve the usage time per reviewer

To compute the total usage time in seconds per reviewer, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/usage-time/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve size of the extracted text for reviewed documents

To retrieve the size of the extracted text for all documents reviewed per reviewer, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/total-reviewed-text-size/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve an aggregation of user actions by hour

You can aggregate the total distinct document actions performed by each reviewer, grouped by the hour of the day in which the action was performed. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/distinct-document-actions-per-hour-of-day/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve choices reviewed by users

You can retrieve information about the choices reviewed by users in a specific workspace. This endpoint supports retrieving statistics for single choice fields, multiple choice fields, and Yes/No fields. Send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/reviewer-choices/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Retrieve a summary report of reviewer statistics

You can programmatically generate a report similar to the reviewer statistics report available through the Relativity UI. For more information, see Reviewer statistics on the RelativityOne Documentation site.

You must specify the time zone of the reviewers, and indicate whether to include system admin statistics in the data.

To generate a summary report, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.reviewer-statistics/workspaces/{{workspaceID}}/summary-report/

Set the {{workspaceID}} variable to the Artifact ID of a workspace.

Audit Query service

The Audit Query service supports querying for a specific audit record.

Query for an audit record

To read a single audit record, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/{{workspaceID}}/audit/

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Audit Object Manager UI service

The Audit Object Manager UI service supports querying on audit details for display in the Relativity UI. It provides two endpoints for querying:

Review the following guidelines for Audit Object Manager UI service:

Query endpoint

To use the query endpoint, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/query

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Query on audit fields

You can query for specific fields in an audit as illustrated in the following example.

Query for a specific audit object

You can query on a specific audit object as illustrated in the following example.

Query with additional query options

You can set additional query options so that the Details field in the Relativity UI contains an escaped JSON string instead of HTML.

Query on audit fields and return a smaller payload

To use the queryslim endpoint, send a POST request to the following URL:

<host>/Relativity.REST/api/relativity.audit.query/workspaces/<workspaceId>/audit/UI/queryslim

Set the {{workspaceID}} variable to the Artifact ID of a workspace, or use -1 to indicate the admin-level context.

Note: The AuditQueryOptions field isn't available for the queryslim endpoint. For more information, see Query with additional query options.

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget