Staging Reports API (REST)

The Staging Reports API (also known as the Staging Insights API) provides a REST service that allows you to generate folder and file reports about tenant data stored in staging areas. This guide will help you get started with the API, including making your first requests, understanding the available endpoints, and authenticating your API calls.

With this API you can:

• Enumerate folders in staging containers.
• Generate folder or file reports from staging data.
• Retrieve lists of submitted reports.
• Retrieve generated reports as downloadable files.

• Access billable summary reports for contracted staging allowance tracking.

The service accepts and returns JSON-encoded requests and uses standard HTTP response codes, authentication, and verbs.

Resources

Staging Reports REST API (V4) Reference

Permissions

The account used to access the Staging Reports API requires the View Admin Repository instance permission and one of the following permissions:

• View Client Domain Staging Reports
  • Allows users to create Staging Reports for staging containers/fileshares they have access to.
  • With this permission, the account must be assigned to the specific fileshares they want to access. See Granting user access to specific fileshares for details in the procedure.
  • This permission is suitable for users who need to generate reports for specific client domains or tenant data.
• View Instance-wide Staging Reports
  • Allows users to create Staging Reports across all staging containers/fileshares in the instance.
  • With this permission, the account's assignment to specific fileshares is not checked.
  • This permission is ideal for administrators, finance team members, or API accounts that need comprehensive access for billing and monitoring purposes.

See Setting instance permissions in the RelativityOne User Guide for the procedure to set permissions.

Considerations

• When the parameter UseSnapshot is set to false, you cannot run reports on top level folders (e.g. t019/ARM/), but only from 2nd level onward (e.g. t019/ARM/1017587_WS2_20191223215604 or subsequently-nested folders)
• When the parameter UseSnapshot is set to true:
  • You cannot include file-level details.
  • The value for includeFiles must be set to false. Otherwise, it returns an error.

• Staging Reports are retained in the report list for 7 days.

• If you encounter issues viewing Unicode characters when opening CSV files in Excel, enable UTF-8 encoding within Excel settings. For more information, see How to open UTF-8 CSV file in Excel.

• Sizes On Demand Reports cannot be generated at the top level folder (e.g. t001\ARM). You must select a sub-folder within the top level folder to generate the report (e.g. t001\ARM\ExampleSubFolder).

• To view data volumes across the top level folders, use either Billable Summary Reports or Last Recorded Sizes Reports

• CSV reports have a limitation of 1 million records. The job will halt during report generation once 1 million records have been added to the CSV report. The limit can be reached with 1 million folders or files, depending on whether file level details have been included.

• Generating reports may take an extended period of time depending on the number of files and subfolders.

URLs

The URLs for the REST API endpoints use the tenant URL format with version v4:

1
<host>/Relativity.Rest/API/staging-insights/v4/

RelativityOne REST API authentication

To access the Staging Reports API, you must authenticate your requests. For more information on authentication methods, see RelativityOne REST API Authentication.

• Basic authentication is no longer supported.
• Ensure that no cookies are included in requests as it can cause authorization problems.

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.
Copy

curl -X GET "<host>/api/<servicename>/<versionnumber>/<endpoint>" \
     -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 there's a restriction on the number of requests you can make within a given timeframe.

Currently, you are allowed to send 65 requests per 60-second.

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.

Postman sample file

You can use a Postman sample file to become familiar with making calls to endpoints on the service. Download the sample file from Staging Inisghts API Postman file.

To get started with Postman, complete these steps:

1. Obtain access to a Relativity environment. You need a username and password to make calls to your environment.
2. Install Postman.
3. Import the Postman sample file for the service. For more information, see Working with data files on the Postman web site.
4. Select an endpoint. Update the URL with the domain for your Relativity environment and any other variables.
5. In the Authorization tab, set the Type to Basic Auth, enter your Relativity credentials, and click Update Request.
6. See the following sections on this page for more information on setting required fields for a request.
7. Click Send to make a request.

API endpoints/Operations

Get containers

To retrieve available staging containers (tenant data storage areas), send a GET request with the following URL format:

1
<host>/relativity.rest/api/staging-insights/v4/Directory/containers

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "containers": [
    {
      "containerName": "t021"
    },
    {
      "containerName": "t021a"
    },
    {
      "containerName": "t030"
    }
  ]
}

List directories

To list directories within a staging container path, send a POST request with the following URL format and request body:

1
<host>/Relativity.Rest/API/staging-insights/v4/directory/directories

1
2
3
4
5
6
7
{
  "path": "t021/ARM/Test",
  "paging": {
    "start": 1,
    "limit": 300
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "path": "t021/ARM/Test",
  "dirs": [
    "t021/ARM/Test/Folder-1",
    "t021/ARM/Test/Folder-2",
    "t021/ARM/Test/ProcessedData",
    "t021/ARM/Test/Archives"
  ],
  "paging": {
    "start": 1,
    "limit": 300
  }
}

Generate new report

To generate a new staging report, send a POST request with the following URL format and request body:

1
<host>/Relativity.Rest/API/staging-insights/v4/reports

1
2
3
4
5
6
{
  "path": "t021/ARM/Test",
  "useSnapshot": false,
  "includeFiles": false,
  "depth": "TwoLevelsDeep"
}

1
2
3
4
5
6
{
  "path": "t021/ARM/Test",
  "useSnapshot": false,
  "includeFiles": false,
  "depth": 2
}

The depth parameter accepts the following values (as string or integer):

• TopLevelOnly or 0: Report only the top-level directory
• OneLevelDeep or 1: Include one level of subdirectories
• TwoLevelsDeep or 2: Include two levels of subdirectories
• FullHierarchy or -1: Include the complete directory hierarchy

1
2
3
{
  "reportId": "159b1276-8c12-4ac1-b58b-fb4dc656dd89"
}

Generate new summary report

The POST /Reports endpoint accepts an optional date parameter (YYYYMMDD). When the date is provided, the API does not scan storage; instead it produces a summary report from the billable summary CSV available for that container/date combination.

To retrieve a new summary report, send a POST request with the following URL format:

<host>/relativity.rest/api/staging-insights/v4/Reports

1
2
3
4
{
  "path": "t021",
  "date": "20260124"
}

{
  "path": "t021/ARM/1014823_New_Case_Template",
  "date": "20260124"
}

• path is the container-scoped path. The first segment must be a valid container name (e.g. t021). When a second segment is present it must be one of the allowed staging directories (ARM, TenantVM, ProcessingSource, StructuredData). Up to 5 segments total are allowed (container + up to 4 sub-path segments).
• When path equals just the container name, the entire billable summary CSV for that container/date is returned. When path includes a sub-path, the CSV is filtered to lines whose first column starts with that path.
• depth, useSnapshot, and includeFiles are accepted by the model but ignored — the billable summary CSV has a fixed structure, so these parameters do not affect the output.
• The response uses the same ReportResponse shape (reportId) as a regular report.

1
2
3
{
  "reportId": "9b8d13d0-5e0f-4d14-9b5c-2b6dd2f60ec7"
}

List reports

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

1
<host>/relativity.rest/api/staging-insights/v4/Reports?start={{start}}&limit={{limit}}&includeSnapshotReports={{includeSnapshotReports}}&includeSummaryReports={{includeSummaryReports}}

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
{
  "reportJobs": [
    {
      "reportId": "bae8dadf-c5b3-4d86-abfc-cce9f49455b7",
      "path": "t021/ARM/TestFolder-1",
      "createdOn": "2023-11-17T14:21:35.2681337Z",
      "state": "Succeeded",
      "includeFiles": false,
      "useSnapshot": false,
      "depth": "TopLevelOnly"
    },
    {
      "reportId": "e3f1bd73-a578-4e86-a423-f4340b0a1f0d",
      "path": "t021/ARM/TestFolder-200",
      "createdOn": "2023-11-17T14:20:47.9840466Z",
      "state": "Processing",
      "includeFiles": true,
      "useSnapshot": false,
      "depth": "FullHierarchy"
    }
  ],
  "paging": {
    "start": 1,
    "limit": 200
  }
}

Get report file

To retrieve a generated report file, send a GET request with the following URL format:

1
<host>/Relativity.Rest/API/staging-insights/v4/reports/{{reportId}}/file

Response:
Returns the generated report file as a downloadable CSV or other formatted file.

Cancel report

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

1
<host>/Relativity.Rest/API/staging-insights/v4/reports/{reportId}

1
true

Get billable summary reports

The billable summary report is a pre-formatted CSV containing a directory list of all folders, at three levels of depth, that count towards the contracted staging allowance.

To retrieve a billable summary report file, send a GET request with the following URL format:

1
<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports/file?container={{container}}&date={{date}}

Date should be in YYYYMMDD format.

Response:
Returns a CSV file containing the billable summary data.

Get billable summary report list

To retrieve a list of available billable summary reports, send a GET request with the following URL format:

<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports?start={{start}}&limit={{limit}}

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "reports": [
    {
      "container": "t021",
      "date": "2023-11-17T14:21:35.2681337Z"
    },
    {
      "container": "t021a",
      "date": "2023-11-17T14:20:47.9840466Z"
    }
  ],
  "totalCount": 2
}

Get latest billable summary report per container

To retrieve the most recent billable summary report for each unique container the caller has access to, send a GET request:

<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports/latest

This endpoint is useful when you only want the freshest snapshot per container without having to page through the full list.

1
2
3
4
5
6
7
8
9
10
11
12
{
  "reports": [
    {
      "container": "t021",
      "date": "2026-01-24T00:00:00Z"
    },
    {
      "container": "t021a",
      "date": "2026-01-22T00:00:00Z"
    }
  ]
}

Get billable summary report directory details

To retrieve details for a specific directory inside a billable summary report, send a POST request with the container, report date, and target path to the following URL format:

<host>/relativity.rest/api/staging-insights/v4/billable-summary-reports/directory-details

• date must be in YYYYMMDD format and match an existing billable summary report.
• path is relative to the container. Use an empty string ("") to target the container root. A path of / is normalized to the root and is therefore equivalent to"".
• This endpoint may return 403 Forbidden if the authenticated caller does not have access to the requested container. This is distinct from 401 Unauthorized, which indicates an authentication failure.
• This endpoint is rate-limited and may return 429 Too Many Requests.

1
2
3
4
5
{
  "container": "t021",
  "date": "20260124",
  "path": "ARM/Test Folder (2024)"
}

1
2
3
4
5
6
7
8
{
  "name": "ARM/Test Folder (2024)",
  "level": 2,
  "sizeBytes": 1234567890,
  "files": 4321,
  "createdDateUtc": "2024-04-12T10:15:00Z",
  "lastModifiedDateUtc": "2026-01-23T18:42:11Z"
}

PowerShell code samples for staging reports

Set variables

Use values from your environment

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

Obtain access token

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

1
2
3
4
5
6
7
8
9
10
11
12
#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

Set headers and Uri for staging reports

These headers are used specifically for making requests to the staging reports API.

1
2
3
4
5
$headersToUseWithStagingReports = @{
  Authorization = "Bearer $token"
  'Content-Type' = "application/json"
}
$requestUri = "$relativityHost/relativity.rest/api/staging-insights/v4"

Retrieve containers

Send a GET request to fetch available staging containers.

1
2
3
4
# Send request to fetch containers
$containersResponse = Invoke-RestMethod -Uri "$requestUri/Directory/containers" -Method GET -Headers $headersToUseWithStagingReports
# Convert and display the response as JSON
$containersResponse | ConvertTo-Json

List directories

Send a POST request to list directories within a specific staging container path.

1
2
3
4
5
6
7
8
9
10
11
12
# Define the request body for directory listing
$directoryListBody = @{
    path = "t021/ARM/Test"
    paging = @{
        start = 1
        limit = 300
    }
} | ConvertTo-Json -Depth 3
# Send request to list directories
$directoriesResponse = Invoke-RestMethod -Uri "$requestUri/Directory/directories" -Method POST -Headers $headersToUseWithStagingReports -Body $directoryListBody
# Display the response
$directoriesResponse | ConvertTo-Json

Generate a new report

Send a POST request to generate a new staging report.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Define the request body for report generation (using string value)
$reportRequestBody = @{
    path = "t021/ARM/Test"
    useSnapshot = $false
    includeFiles = $false
    depth = "TwoLevelsDeep"
} | ConvertTo-Json -Depth 3

# Define the request body for report generation (using integer value)
$reportRequestBodyWithInt = @{
    path = "t021/ARM/Test"
    useSnapshot = $false
    includeFiles = $false
    depth = 2
} | ConvertTo-Json -Depth 3

# Send request to generate report
$reportResponse = Invoke-RestMethod -Uri "$requestUri/Reports" -Method POST -Headers $headersToUseWithStagingReports -Body $reportRequestBody

List all reports

Send a GET request to fetch all staging reports.

1
2
3
4
5
# Send request to fetch reports
$reportsResponse = Invoke-RestMethod -Uri "$requestUri/Reports?start=1&limit=200" -Method GET -Headers $headersToUseWithStagingReports

# Convert and display the response as JSON
$reportsResponse | ConvertTo-Json -Depth 3

Get specific report file

Send a GET request to download a specific report file.

1
2
3
4
5
6
7
8
# Define report ID (replace with actual report ID)
$reportId = "159b1276-8c12-4ac1-b58b-fb4dc656dd89"

# Send request to download report file
$reportFileResponse = Invoke-WebRequest -Uri "$requestUri/Reports/$reportId/file" -Method GET -Headers $headersToUseWithStagingReports -OutFile "staging-report-$reportId.csv"

# Display the response
Write-Host "Report file downloaded to staging-report-$reportId.csv"

Cancel report

Send a DELETE request to cancel a specific report.

1
2
3
4
5
# Send request to cancel report
$cancelResponse = Invoke-RestMethod -Uri "$requestUri/Reports/$reportId" -Method DELETE -Headers $headersToUseWithStagingReports

# Display the response
$cancelResponse

Summary

• Replace <host> with your own host when using the samples.
• The access token is obtained via client credentials authentication.
• The Staging Reports API requires Bearer Token Authorization.
• The Staging Reports API uses v4 endpoints and supports comprehensive analysis of tenant data in staging containers.