Usage Reports API

RelativityOne Government tenants will have access to Usage Reports starting late 2025.

This guide will help you get started with the Usage Reports API, including making your first requests, understanding the available endpoints, and authenticating your API calls.

Guidelines for the Usage Reports API

Review the following guidelines for working with this API.

Permissions

To use the Usage Report API, you need the following instance-level permissions:

View Client Domain Usage Reports
- Allows users to create Usage Reports across the workspaces they have access to.
- This permission is suitable for users who need to generate reports for specific client domains.
View Instance-wide Usage Reports
- Allows users to create Usage Reports across the entire instance (all workspaces), even without direct access to those workspaces.
- This permission is ideal for roles like customer finance team members or API account users who need to generate reports for client billing.
- System Administrators must also be assigned the View Instance-wide Usage Reports permission in order to generate reports across all workspaces. For more information, see Setting instance permissions.

URLs

The URLs for the REST API endpoints include a path parameter {version} that you need to set before making a call:

Copy

1
<host>/api/usage-reports/{version}

Replace {version} with the API version you want to use, for example v1.

Copy

1
<host>/api/usage-reports/v1/metadata

RelativityOne REST API Authentication

Overview

To access the Usage Reports API, you must authenticate your requests. RelativityOne supports several authentication methods:

Cookie Authentication
Bearer Token Authentication

Basic authentication is no longer supported.

For more information on authentication methods, see RelativityOne REST API Authentication documentation.

Cookie Authentication

When a user logs into Relativity, the RelAuth cookie is issued to the browser. This encrypted cookie contains the information that validates the user. This cookie can be passed to REST service call instead of an HTTP authorization header. If the encrypted cookie is valid, the call will be authenticated under the credentials of the user who logged in via the web.

Cookie Authentication in JavaScript

You don't need to include an additional Authorization header when using cookie authentication from JavaScript within Relativity. The browser performs the authentication. See the following code sample:

Copy

1
2
curl -X GET "<host>/api/usage-reports/v1/metadata" \
        -H "Cookie: RelativityAuth=your_cookie_value"

Bearer Token Authentication

You can also connect to the REST services using bearer token authentication. When using bearer token authentication, clients access the service with an access token issued by the Relativity identity service based on a consumer key and secret obtained through an OAuth2 client.

When multiple web servers are hosted behind a load balanced route, you can't programmatically retrieve an authentication token. You must use a direct route to one of the web servers to retrieve the authentication token.

To get an access token:

Create a Relativity OAuth2 Client:
- Click Home > Authentication > OAuth2 Client Manager.
- Click New OAuth2 Client to create a new client, or click Edit to modify an existing client.
- Complete the fields on the form, fields in orange are required:
  - Name- enter a unique name for the OAuth2 client.
  - Enabled- indicate whether the client will have access to Relativity.
  - Flow Grant Type- select Client Credentials.
  - Context User- select a user who is a member of the Relativity Administrators group.
  - Access Token Lifetime- set the duration (in minutes) for which access tokens are valid. The recommended value is 60 minutes.
- Click Save to create the OAuth2 client. For more information, see OAuth2 clients on the RelativityOne Documentation site.

Obtain a Bearer Token:

Send a POST request to the token endpoint with your credentials.

Copy

1
2
3
curl -X POST "<host>/Relativity/Identity/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=SystemUserInfo"

Include the obtained token in the Authorization header of your API requests.

Copy

1
2
curl -X GET "<host>/api/usage-reports/v1/Metadata" \
     -H "Authorization: Bearer your_access_token"

API Endpoints

Get metadata

To retrieve metadata fields for report creation, send a GET request with a URL in the following general format:

Copy

1
<host>/api/usage-reports/v1/metadata

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
{
  "origins": [
    {
      "metrics": [
        {
          "id": "18af070c-5f4a-407b-a4c8-93b1c4fffc34",
          "name": "Workspace Artifact ID",
          "description": "The unique identifier for the workspace within the instance.",
          "valueType": "Int64",
          "originId": "35dff1e2-c391-4fa4-9897-0999358f8c13",
          "reportType": "Workspace",
          "isDefault": false
        },
        {
          "id": "bd708c94-c51b-44e5-bc2d-29378fe72bf7",
          "name": "Report Period",
          "description": "The month and year that the workspace utilization metrics covers. This will be formatted in month/year.",
          "valueType": "DateTime",
          "originId": "35dff1e2-c391-4fa4-9897-0999358f8c13",
          "reportType": "Workspace",
          "isDefault": false
        }
      ],
      "id": "35dff1e2-c391-4fa4-9897-0999358f8c13",
      "name": "Workspace Utilization"
    },
    {
      "metrics": [
        {
          "id": "6f9619ff-8b86-d011-b42d-00c04fc964ff",
          "name": "Workspace Artifact ID",
          "description": "The unique identifier for the Workspace within the instance.",
          "valueType": "Int64",
          "originId": "229954a5-052d-4c67-b144-5e07847a52f4",
          "reportType": "Workspace",
          "isDefault": false
        },
        {
          "id": "59f7c2a8-feb3-4ee0-8f4a-d7359ee58d17",
          "name": "Processing Data Source Count",
          "description": "The number of data sources for the processing set where the status is either “Completed” or “Completed with Errors”.",
          "valueType": "Int64",
          "originId": "229954a5-052d-4c67-b144-5e07847a52f4",
          "reportType": "Workspace",
          "isDefault": false
        }
      ],
      "id": "229954a5-052d-4c67-b144-5e07847a52f4",
      "name": "Processing Statistics"
    },
    {
      "metrics": [
        {
          "id": "f0931643-5aee-414a-9c53-495b71bae5fc",
          "name": "Contracts Document Units",
          "description": "The total number of document units processed using Relativity Contracts.",
          "valueType": "Int64",
          "originId": "eb6ba799-31fc-4f92-abff-690dd341cd08",
          "reportType": "Workspace",
          "isDefault": false
        },
        {
          "id": "241df315-c954-405f-8d09-0ac5cfdb7de3",
          "name": "Current Data Breach File Size ",
          "description": "The current size of data included in Data Breach Response.",
          "valueType": "Double",
          "originId": "eb6ba799-31fc-4f92-abff-690dd341cd08",
          "reportType": "Workspace",
          "isDefault": false
        }
      ],
      "id": "eb6ba799-31fc-4f92-abff-690dd341cd08",
      "name": "Processing Utilization"
    },
    {
      "metrics": [
        {
          "id": "a6bda9d5-23d7-4b6c-86f8-513d55e8f66e",
          "name": "User Email Address",
          "description": "The email address associated to the user.",
          "valueType": "Text",
          "originId": "3f7d2ad3-e7d3-4866-bda2-4c7494dcc690",
          "reportType": "User",
          "isDefault": true
        },
        {
          "id": "39a5b2b5-6aef-4d67-9bc4-f63c730883f9",
          "name": "Enabled User Information Capture Date-Time",
          "description": "The date/time that the enabled user information were captured from the instance. The value is shown in UTC.",
          "valueType": "DateTime",
          "originId": "3f7d2ad3-e7d3-4866-bda2-4c7494dcc690",
          "reportType": "User",
          "isDefault": true
        }
      ],
      "id": "3f7d2ad3-e7d3-4866-bda2-4c7494dcc690",
      "name": "User Information"
    },
    {
      "metrics": [
        {
          "id": "bc1caedc-e3f9-4d29-a4cb-04e7942f598f",
          "name": "Workspace ArtifactID",
          "description": "The unique identifier for the workspace within the instance. Including this field creates a many-to-many relationship table between user information and workspace details.",
          "valueType": "Int64",
          "originId": "30d758e1-76f7-486f-8579-e4b5a361e75c",
          "reportType": "User",
          "isDefault": false
        },
        {
          "id": "a871c32c-854b-4b49-ac00-5aa005f58c9a",
          "name": "Workspace Name",
          "description": "The name of the workspace. Including this field creates a many-to-many relationship table between user information and workspace details.",
          "valueType": "Text",
          "originId": "30d758e1-76f7-486f-8579-e4b5a361e75c",
          "reportType": "User",
          "isDefault": false
        }
      ],
      "id": "30d758e1-76f7-486f-8579-e4b5a361e75c",
      "name": "Workspace Information"
    }
  ]
}

List reports

To list all reports, send a GET request with a URL in the following general format:

Copy

1
<host>/api/usage-reports/v1/reports

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
  "reports": [
    {
      "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
      "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
      "name": "Report 01/01/2024",
      "dateRange": {
        "from": "2024-01-01T00:00:00Z",
        "to": "2024-01-31T00:00:00Z"
      },
      "fields": [
        "233c0387-a246-4b9f-80b4-772ab8d41062",
        "4b7a9d1f-8c3e-4e0c-8d2b-9a6a5c0f3e1a",
        "3749241a-d2f7-45d3-a798-0ab7d20c8b71",
        "89b2fc03-8cd9-494c-8204-4a62fd05975b",
        "05b152e6-c56c-40fd-a4ef-853efa4ba624",
        "f68f2d4c-ba9a-4831-a903-113ad5ce4b91",
        "ece1332d-39ba-4460-a50e-345deba7af05",
        "61bc4e25-ce8e-415c-bb55-6863f3844af0"
      ],
      "status": "Finished",
      "createdAt": "2024-02-01T12:00:00.8222732+00:00",
      "type": "Workspace",
      "version": 1
    },
    {
      "id": "61203fa6-e526-4d65-9e01-ef7002b215e9",
      "tenantId": "533d225b-955b-4693-9078-505f1018bfcf",
      "name": "Report 05/01/2024",
      "dateRange": {
        "from": "2024-05-01T00:00:00Z",
        "to": "2024-05-31T00:00:00Z"
      },
      "fields": [
        "4c1fa36e-0fda-4f6a-abb9-2d542be04fd2",
        "e42e478d-5dcc-49bd-b91b-3de824a92c3a",
        "6bd6b190-85ff-49a9-832d-e66a07959b3d",
        "bc1caedc-e3f9-4d29-a4cb-04e7942f598f",
        "a871c32c-854b-4b49-ac00-5aa005f58c9a",
        "27e8b363-7f6a-4d85-be85-32533b3f3f5a",
        "965e287d-cc4a-4501-b43a-b7fb3f1cfd0a",
        "a6bda9d5-23d7-4b6c-86f8-513d55e8f66e",
        "39a5b2b5-6aef-4d67-9bc4-f63c730883f9"
      ],
      "status": "Scheduled",
      "createdAt": "2024-06-1T009:26:54.7540367+00:00",
      "type": "User",
      "version": 1
    }
  ]
}

Generate new report

To generate a new report, send a POST request with a URL in the following general format:

Copy

1
<host>/api/usage-reports/v1/reports

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "name": "Report 05/05/2024",
  "dateRange": {
    "from": "2024-05-05",
    "to": "2024-05-05"
  },
  "fields": [
    "4f8b9cf2-8e45-4b27-babc-3753e8a77f8c",
    "ece1332d-39ba-4460-a50e-345deba7af05",
    "29b400b3-4f47-4f8c-badf-94e2a5969763",
    "fcfdb1b9-0207-4851-a8f9-b653e4bbc851",
    "40d897b5-113a-42e8-a354-2580b726d757",
    "95d37233-b2d9-4e19-8f31-2304389ddbc0"
  ]
}

When sending a request to create a report, ensure that all selected metrics belong to the same reportType. The reportType can either be Workspace or User. Mixing metrics with different reportType values (e.g., Workspace and User) in the same request is not allowed and will result in an error.

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
  "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
  "name": "Report 05/05/2024",
  "dateRange": {
    "from": "2024-05-05T00:00:00Z",
    "to": "2024-05-05T00:00:00Z"
  },
  "fields": [
    "233c0387-a246-4b9f-80b4-772ab8d41062",
    "4b7a9d1f-8c3e-4e0c-8d2b-9a6a5c0f3e1a",
    "3749241a-d2f7-45d3-a798-0ab7d20c8b71",
    "89b2fc03-8cd9-494c-8204-4a62fd05975b",
    "05b152e6-c56c-40fd-a4ef-853efa4ba624",
    "f68f2d4c-ba9a-4831-a903-113ad5ce4b91",
    "ece1332d-39ba-4460-a50e-345deba7af05",
    "61bc4e25-ce8e-415c-bb55-6863f3844af0"
  ],
  "status": "Finished",
  "createdAt": "2024-06-06T12:00:00.8222732+00:00",
  "type": "Workspace",
  "version": 1
}

Download report by ID

To download a specific report, send a GET request with a URL in the following general format:

Copy

1
<host>/api/usage-reports/v1/reports/download/{id}

Copy

Response:

1
File(stream, application/octet-stream)

Get report

To get the details of a specific report, send a GET request with the following URL format:

Copy

1
<host>/api/usage-reports/v1/reports/{id}

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
  "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
  "name": "Report 01/01/2024",
  "dateRange": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T00:00:00Z"
  },
  "fields": [
    "233c0387-a246-4b9f-80b4-772ab8d41062",
    "4b7a9d1f-8c3e-4e0c-8d2b-9a6a5c0f3e1a",
    "3749241a-d2f7-45d3-a798-0ab7d20c8b71",
    "89b2fc03-8cd9-494c-8204-4a62fd05975b",
    "05b152e6-c56c-40fd-a4ef-853efa4ba624",
    "f68f2d4c-ba9a-4831-a903-113ad5ce4b91",
    "ece1332d-39ba-4460-a50e-345deba7af05",
    "61bc4e25-ce8e-415c-bb55-6863f3844af0"
  ],
  "status": "Finished",
  "createdAt": "2024-02-01T12:00:00.8222732+00:00",
  "type": "Workspace",
  "version": 1
}

Get report details

To get detailed information of a report with pagination, send a GET request with a URL in the following general format:

Copy

1
<host>/api/usage-reports/v1/reports/{id}/details?pageNumber={pageNumber}&amp;pageSize={pageSize}

Copy

Sample JSON response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "fields": [
    "233c0387-a246-4b9f-80b4-772ab8d41062",
    "4b7a9d1f-8c3e-4e0c-8d2b-9a6a5c0f3e1a",
    "3749241a-d2f7-45d3-a798-0ab7d20c8b71",
    "89b2fc03-8cd9-494c-8204-4a62fd05975b",
    "05b152e6-c56c-40fd-a4ef-853efa4ba624",
    "f68f2d4c-ba9a-4831-a903-113ad5ce4b91",
    "ece1332d-39ba-4460-a50e-345deba7af05",
    "61bc4e25-ce8e-415c-bb55-6863f3844af0"
  ],
  "items": [
    [
      "R1 - Report - 1",
      "RelativityOne Review Template (v4.0.0)",
      "Relativity Template",
      "Relativity Template",
      "2024-08-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 2",
      "RelativityOne Investigations Template (v2.1.1)",
      "Relativity Template",
      "Relativity Template",
      "2024-08-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 3",
      "RelativityOne Automation",
      "Relativity Template",
      "Relativity Template",
      "2024-08-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 4",
      "RelativityOne Maintenance",
      "Relativity Template",
      "Relativity Template",
      "2024-08-01T04:46:00",
      null,
      1.32,
      0
    ],
    [
      "R1 - Report - 5",
      "RelativityOne Template for ClientDomain",
      "ClientDomain",
      "ClientDomain Matter",
      "2024-08-01T04:46:00",
      null,
      0,
      0
    ]
  ],
  "currentPage": 1,
  "pageSize": 10,
  "totalItems": 5
}

Delete Report

To delete a specific report, send a DELETE request with the following URL format:

Copy

1
<host>/api/usage-reports/v1/reports/{id}

Copy

Sample response

1
"1240a7dd-5338-4046-9e00-41f9a8be9add"

PowerShell code samples for Usage Reports

The following section describes how to use PowerShell for Usage Reports.

Set variables

Use the following PowerShell scripts to set variables, use values from your environment.

Copy

$relativityHost = "<host>"
$clientId = "XXX"
$clientSecret = "XXX"

Obtain access token

Use the following PowerShell scripts to authenticate and retrieve an access token.

Copy

Define headers, Uri and body for authentication

$tokenHeaders = @{
'Content-Type' = 'application/x-www-form-urlencoded'
}
$tokenUri = "$relativityHost/Relativity/Identity/connect/token"
$tokenBody = "grant_type=client_credentials&client_id=$clientId&client_secret=$clientSecret&scope=SystemUserInfo"

Copy

Request access token

$accessToken = Invoke-RestMethod -Uri $tokenUri -Headers $tokenHeaders -Body $tokenBody -Method POST

Copy

Extract the token (only the access token, not the full response)

$token = $accessToken.access_token

Set headers and Uri for Usage Reports.

Use the following PowerShell script to set headers and Uri for Usage Reports. These headers are used specifically for making requests to the Usage Reports API, which does not use Kepler.

Copy

$headersToUseWithUsageReports = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}
$requestUri = "$relativityHost/api/usage-reports/v1/Reports"

Retrieve usage reports

Use the following PowerShell script to send a GET request to fetch Usage Reports.

Copy

Send request to fetch usage reports

$response = Invoke-RestMethod -Uri $requestUri -Method GET -Headers $headersToUseWithUsageReports

Copy

Convert and display the response as JSON

$response | ConvertTo-Json

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet