Billing Insights API (REST)

The Billing Insights API provides a REST service that allows you to retrieve billing insights data about your RelativityOne tenant. The API is read-only and there are no mechanisms within the API to manipulate the data it returns.

With this API you can check billing metrics breakdowns by instance, workspace, matter, and client. Typical use-cases:

  • Comparing billing costs between review, repository, and cold storage workspace.

  • Checking peak values against current usage for the whole instance or specific workspaces.

  • Retrieving details of the users who are billed for in a given month.

The data returned by the Billing Insights API is used in the Cost Explorer, and is refreshed daily. Please refer to the Cost Explorer documentation for a user-friendly explanation of the Billing Insight API field’s contents.

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

Note: Due to the nature of the Billing Insights API, queries against the API should use a Production RelativityOne Instance ID within your request body. As Sandbox instances do not have any associated billing data, you will not receive any data in response when using a Sandbox Instance ID within your request body. Your instance’s Instance ID can be found within the Management Console Cost Explorer tab, in the column Instance ID

Resources

Methods

The Billing Insights API consists of 3 endpoints:

  • month-details - retrieve monthly billing metrics at the specified level (Workspace, Matter, Client, Instance)
    • Billing metrics categories:
      • Relativity_Contracts_Document - metrics for Relativity Contracts
      • Relativity_Storage_Review - metrics for review data
      • Relativity_Storage_Repository - metrics for repository data
      • Relativity_Storage_ColdStorage - metrics for cold storage data
      • Relativity_Storage_Staging - metrics for staging data
      • Relativity_Translate - metrics for translate data
      • Relativity_Users_RelOne - metrics for Relativity One users
      • Relativity_Users_Server - metrics for Relativity Server users
      • Relativity_Users_NonBillable - metrics for not billable users
  • users-details - get a user list with billing attributes for a given date, for example to check which users are billable or some of the user attributes
  • hierarchy-lookup - get artifact ids for workspace, matter, client and instance, which could be useful for filtering billing user and month details

Authentication

The Billing Insights API uses a Bearer token to authenticate requests. Follow these steps to generate a bearer token:

  1. Create OAuth2 Client by following instructions on this page (here and below): OAuth2 client
  2. Generate bearer token following instructions in the Bearer token authentication section of this topic: REST API authentication.
  3. Use the bearer token to make requests to Billing Insights API endpoints (refer to the details for each endpoint)
Note: The context user account associated with the OAuth Client (and therefore the Bearer token), must have permission to access the Cost Explorer. See Cost Explorer - Security Permissions.

Errors

Billing Insights API uses conventional HTTP response codes to indicate the success or failure of an API request. Generally, codes in the 2xx range indicate success; codes in the 4xx range indicate an error that failed given the information provided (for example a required parameter was omitted); codes in the 5xx range indicate an internal error with the Billing Insights API.

Response Codes

  • 200 - OK: everything worked as expected
  • 400 - Bad Request: The request was unacceptable, often due to missing a required parameter
  • 401 - Unauthorized: No valid token provided
  • 401 - Forbidden: API key doesn't have permission to perform the request
  • 404 - Not Found: requested resource doesn't exist
  • 5xx - Server Errors: Something went wrong on Billing Insights API end

Pagination

The API uses pagination based mainly on top and skip parameters. To use pagination, specify how many records you want to skip and how many records you are going to fetch.

  • pagingRequest - specifies paging options
  • top [int] - return top N records
  • skip [int] - exclude first N records
  • maxItemCount [int] - specifies a maximum number of records that should be returned from the API. If there are more records to fetch, the continuationToken is returned in the pagingResponse.
  • includeCount [bool] - specifies that totalRecordCount should be included in the pagingResponse.

Remarks

  • top and skip values need to be either empty or populated. Specifying just a single value is considered a bad request.
  • if top and skip are specified and maxItemCount is not specified, continuationToken will not be returned. The API guarantees that all the records were populated, and there is no need to fetch additional records. In all other cases, continuationToken might be returned, indicating there are more records to fetch.

Sorting

API allows sorting data based on the specified field. To do that you need to populate the order field:

Order:

  • fieldName - specifies the field name which should be used for sorting the results. The field matches the structure of the response payload, with the exception that all the property names should be in the upper case instead of the lower case.
  • direction - specifies the sort direction. Possible values: Asc, Desc.

Hashing

Billing data may be returned in a hashed format via the API, if the instance settings are configured to replace values with hashed values. If you see that data returned from the API is hashed and you want to explore the real values, you can use the Object Manager API to match object IDs, and then replace the hashed values with the values returned from the Object Manager API.

Possible hashed values include:

  • Workspace Name
  • Client Name
  • Client Number
  • Matter Name
  • Matter Number
  • Email Address

You can determine which values are hashed using the anonymizedFields property. The property includes a map of the property name and value if that property is hashed. For example:

Copy 
"matter": {
  "artifactID": 1000002,
  "name": "DtilJxyprs4jkymmvKgmOklRWrs=",
  "anonymization": "Hashed",
  "anonymizedFields": {
    "name": "Hashed",
    "number": "None"
  },
  "number": "1"
}        

Client code generation

To generate client code you can use many tools that support OAS standard e.g. NSwagStudio and provided Billing Insights API OAS file. See the topic How to generate client code

Code Samples

Calling the Billing API with generated client code

Copy

Retrieve the top 10 workspaces sorted by billable value of Relativity_Storage_Review metric.

class Program {
  public static async Task Main(string[] args) {
    using
    var httpClient = new HttpClient();
    var token = "TODO add token";
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var billingApiClient = new BillingAPIClient(httpClient);
    billingApiClient.BaseUrl = "https://billing-insights.api.relativity.one";
    var request = new GetMonthDetailsRequest {
      DateKey = "202203",
        MetricKeys = new [] {
          "Relativity_Storage_Review"
        },
        SelectorLevel = HierarchyLevel.Instance,
        Level = HierarchyLevel.Workspace,
        PagingRequest = new PagingRequest() {
          Top = 10, Skip = 0
        },
        Order = new FieldOrder() {
          Direction = OrderDirections.Desc,
            FieldName = "PricedMetrics.Relativity_Storage_Review.BillableValue"
        }
    };

    var result = await billingApiClient.MonthDetailsAsync("1", request);

    foreach(var responseItem in result.Results) {
      Console.WriteLine($"{responseItem.Instance.Name} - {responseItem.Workspace?.Name} - {responseItem.Matter?.Name} - {responseItem.PricedMetrics["
        Relativity_Storage_Review "].BillableValue } - peak date - {responseItem.PricedMetrics["
        Relativity_Storage_Review "].CollectionTimeUtc} ");
    }
  }
}

Version History

Release Notes
  • Added a new field (workspaceStatus) to Workspace
  • Modified the meaning of activityStatus
Release Notes
  • Initial Version