Last date modified: 2026-Jun-02

Usage Reports API

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:

  1. 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.
  2. 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 
<host>/api/usage-reports/{version}
  • Replace {version} with the API version you want to use, for example v1.
Copy 
<host>/api/usage-reports/v1/metadata

RelativityOne REST API Authentication

To access the Usage Reports API, you must authenticate your requests. RelativityOne supports Bearer Token Authentication.

Basic authentication is no longer supported.

Bearer Token Authentication

You can 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 create, obtain and use a bearer access token:

  1. Create a Relativity OAuth2 Client (for more information see OAuth2 clients on the RelativityOne Documentation site):
    • 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.
  2. Obtain a Bearer Token by sending a POST request to the token endpoint with your credentials.
    Copy
    curl -X POST "<host>/Relativity/Identity/connect/token" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d "grant_type=client_credentials" \
         -d "scope=SystemUserInfo"
         -d "client_id=<your_client_id>" \
         -d "client_secret=<your_client_secret>" \
  3. Use the Bearer Token by including the token in the Authorization header of your API requests.
    4. Copy 
    curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
         -H "Authorization: Bearer <your_access_token>"

The sample below shows how to use the token in a request to the Metadata endpoint of the usage-reports service:

Copy 
curl -X GET "{host}/api/usage-reports/v1/Metadata" \
     -H "Authorization: Bearer {your_access_token}"

Rate Limiting

To ensure fair usage and maintain the stability of our services, we implement rate limiting on our API endpoints. This means that there is a restriction on the number of requests you can make within a given timeframe.

Currently, you're allowed to send 65 requests per 60-second interval.

When you exceed the allowed request limit, your requests will be temporarily blocked, and you'll receive an HTTP 429 Too Many Requests status code.

API Endpoints

Get metadata

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

Copy 
<host>/api/usage-reports/v1/metadata
Copy
Sample JSON response:
{
  "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 
<host>/api/usage-reports/v1/reports
Copy
Sample JSON response:
{
  "reports": [
    {
      "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
      "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
      "name": "Report 01/01/2026",
      "dateRange": {
        "from": "2026-01-01T00:00:00Z",
        "to": "2026-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": "Completed",
      "createdAt": "2026-02-01T12:00:00.8222732+00:00",
      "type": "Workspace",
      "dataMaxPrecision": false,
      "version": 1
    },
    {
      "id": "61203fa6-e526-4d65-9e01-ef7002b215e9",
      "tenantId": "533d225b-955b-4693-9078-505f1018bfcf",
      "name": "Report 02/01/2026",
      "dateRange": {
        "from": "2026-02-01T00:00:00Z",
        "to": "2026-02-28T00: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": "2026-03-01T09: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 
<host>/api/usage-reports/v1/reports
Copy
Sample JSON request:
{
  "name": "Report 03/05/2026",
  "dateRange": {
    "from": "2026-03-05",
    "to": "2026-03-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"
  ],
  "dataMaxPrecision": false
}
  • 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.
  • The dataMaxPrecision flag controls the precision of GB values in the Workspace type report. By default (false), values are rounded to 2 decimal places. Set to true to return values with maximum precision up to 15 decimal places. For User reports, dataMaxPrecision must be omitted or set to null.
  • Each metric returned by the /metadata endpoint includes an isActive flag. When this flag is set to false, the metric is no longer supported in new reports and must be replaced with the corresponding active metric. For more information, see Linked repository metrics migration.
Copy
Sample JSON response:
{
  "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
  "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
  "name": "Report 03/05/2026",
  "dateRange": {
    "from": "2026-03-05T00:00:00Z",
    "to": "2026-03-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": "Completed",
  "createdAt": "2026-03-05T12:00:00.8222732+00:00",
  "type": "Workspace",
  "dataMaxPrecision": false,
  "version": 1
}

Download report by ID

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

Copy 
<host>/api/usage-reports/v1/reports/download/{id}
Copy
Response:
File(stream, application/octet-stream)

Get report

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

Copy 
<host>/api/usage-reports/v1/reports/{id}
Copy
Sample JSON response:
{
  "id": "1240a7dd-5338-4046-9e00-41f9a8be9add",
  "tenantId": "1234565b-955b-4693-9078-505f1018bfcf",
  "name": "Report 01/01/2026",
  "dateRange": {
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-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": "Completed",
  "createdAt": "2026-02-01T12:00:00.8222732+00:00",
  "type": "Workspace",
  "dataMaxPrecision": false,
  "version": 1
}

Get report details

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

Copy 
<host>/api/usage-reports/v1/reports/{id}/details?pageNumber={pageNumber}&pageSize={pageSize}
Copy
Sample JSON response:
{
  "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",
      "2026-03-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 2",
      "RelativityOne Investigations Template (v2.1.1)",
      "Relativity Template",
      "Relativity Template",
      "2026-03-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 3",
      "RelativityOne Automation",
      "Relativity Template",
      "Relativity Template",
      "2026-03-01T04:46:00",
      null,
      0,
      0
    ],
    [
      "R1 - Report - 4",
      "RelativityOne Maintenance",
      "Relativity Template",
      "Relativity Template",
      "2026-03-01T04:46:00",
      null,
      1.32,
      0
    ],
    [
      "R1 - Report - 5",
      "RelativityOne Template for ClientDomain",
      "ClientDomain",
      "ClientDomain Matter",
      "2026-03-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 
<host>/api/usage-reports/v1/reports/{id}
Copy

Sample response

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

PowerShell code samples for Usage Reports

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

Bearer Access tokens in PowerShell

You can use the following sample script to authenticate and retrieve an access token with PowerShell

Copy
Obtaining a Bearer Token in PowerShell
# Set Variables (replace with appropriate values from your environment)
$relativityHost = "<host>"
$clientId = "XXX"
$clientSecret = "XXX"

# 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"

# Request Access Token
$accessToken = Invoke-RestMethod -Uri $tokenUri -Headers $tokenHeaders -Body $tokenBody -Method POST

# Extract the token (only the access token, not the full response)
$token = $accessToken.access_token

You can then use the token in a request, see the example below (replacing the placeholders with the values of the service you are interacting with)

Copy
Using the token in a request
$requestHeadersToUse = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}

# set the endpoint and method type
$requestUri = "$relativityHost/api/<servicename>/<version>/<endpoint>"
$methodType = "GET"

# send the request and get the reponse 
$response = Invoke-RestMethod -Uri $requestUri -Method $methodType -Headers $requestHeadersToUse

# do something with the response
$response | ConvertTo-Json

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 
$requestHeadersToUse = @{
  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 $requestHeadersToUse
Copy
$response | ConvertTo-Json
$response | ConvertTo-Json

Linked repository metrics migration

Some linked repository metrics were originally reported in bytes, indicated by [B] in their display name. These legacy metrics have been superseded by equivalent metrics that report values in gigabytes, [GB]. The legacy metrics remain accessible via the /metadata endpoint and in existing saved reports, but they are marked with isActive: false and must not be used in new report configurations.

To preserve functionality, update any saved report configuration or integration that references a legacy metric GUID by replacing it with the corresponding new GUID from the table below.

You can verify the status of any metric on your own instance by querying /metadata. Legacy GUIDs are returned with isActive: false, and the replacement GUIDs with isActive: true.

Metric Name Legacy metric ID (isActive: false) New metric ID (isActive: true)
Linked Source Workspace ArtifactID 66c27d9c-3832-443d-9ef4-8dbe44a60364 5fd5bfb0-10a3-446b-b49d-d94451a6f60b
Linked Source Image File Size[B]→[GB] 693002b7-efca-47a5-8a19-77f812c3e8ea ade0b9a5-753e-4197-ae5d-1cf2e7113ce9
Linked Source Native File Size[B]→[GB] 52682273-2204-49d4-b1ca-3c163e67da8a 9fd7c224-4a5c-442b-9fed-0aa4401d2be5
Linked Source Production File Size[B]→[GB] 0cdb419c-6156-4013-8598-cb133684543c 14053077-b79c-4689-9e24-a502cc21220e
Linked Source Total File Size[B]→[GB] 2e4cf924-4455-4ef2-ac89-d6ed38c953b0 869514b5-ad22-4cb8-b512-e92fd9c8af3e
Return to top of the page
Feedback