{
  "openapi": "3.0.4",
  "info": {
    "title": "Usage Reports API",
    "description": "Usage Reports is the modern way to gather information and gain oversight across your instance instead of using Relativity scripts, such as Billing Statistics – RelativityOne Case Rollup. Typically, metrics presented in Usage Reports are used for end-client billing, tracking adoption, and general usage metrics. System and Client Domain Administrators can create custom reports at the instance level to report on their workspace utilization and Processing consumption metrics for billing and usage tracking.",
    "version": "v2",
    "x-relativity-api-visibility": "public"
  },
  "servers": [
    {
      "url": "https://{host}.relativity.one/api/usage-reports",
      "variables": {
        "host": {
          "default": "host",
          "description": "Your RelativityOne tenant name"
        }
      }
    }
  ],
  "paths": {
    "/v2/Metadata": {
      "get": {
        "tags": ["Metadata"],
        "summary": "Gets the metadata",
        "description": "Returns a flat list of metrics available for report creation. Unlike v1, metrics are not grouped by origin and do not carry an origin ID.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/FlatMetadataDto"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlatMetadataDto"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlatMetadataDto"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v2/Reports/{id}": {
      "get": {
        "tags": ["Reports"],
        "summary": "Gets the details of a report by ID",
        "description": "This endpoint retrieves basic information about a specific report based on its unique identifier, like report's ID, name, etc.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Reports"],
        "summary": "Delete report",
        "description": "This endpoint allows you to delete processed report.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v2/Reports/{id}/details": {
      "get": {
        "tags": ["Reports"],
        "summary": "Gets the detailed information of a report by ID",
        "description": "This endpoint retrieves detailed information about a specific report based on its unique identifier. The details include all columns, workspaces, and fields that were selected for the report.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "PageNumber",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "PageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDetailsDto"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDetailsDto"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDetailsDto"
                }
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable"
          }
        }
      }
    },
    "/v2/Reports": {
      "get": {
        "tags": ["Reports"],
        "summary": "Lists reports",
        "description": "Retrieves reports for the tenant created within the last MonthCount months. MonthCount defaults to 1 when omitted and must be between 1 and 12 inclusive (values outside this range are rejected with 400). Supports optional server-side pagination (PageNumber, PageSize; PageSize is capped at 1000). When no pagination parameters are supplied, matching reports are returned in the original response shape without paging metadata.",
        "parameters": [
          {
            "name": "PageNumber",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "PageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "MonthCount",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ReportsDto"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportsDto"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportsDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Reports"],
        "summary": "Generate a new report",
        "description": "This endpoint allows you to generate a new report based on the provided request data.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReportRequestDto"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReportRequestDto"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReportRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v2/Reports/download/{id}": {
      "get": {
        "tags": ["Reports"],
        "summary": "Download a report by ID",
        "description": "This endpoint allows you to download a specific report based on its unique identifier.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateReportRequestDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "dateRange": {
            "$ref": "#/components/schemas/DateRangeDto"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          },
          "dataMaxPrecision": {
            "type": "boolean",
            "nullable": true
          },
          "explicitFieldsOnly": {
            "type": "boolean",
            "nullable": true
          },
          "applyDisplayOrder": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "DateRangeDto": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time"
          },
          "to": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      },
      "FlatMetadataDto": {
        "type": "object",
        "properties": {
          "metrics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FlatMetricDto"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "FlatMetricDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "valueType": {
            "enum": ["Text", "Int64", "Double", "DateTime", "Boolean", "Decimal", "Date"],
            "type": "string"
          },
          "reportType": {
            "enum": ["Workspace", "User"],
            "type": "string"
          },
          "isDefault": {
            "type": "boolean"
          },
          "isActive": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "ReportDetailsDto": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "items": {
            "type": "array",
            "items": {},
            "nullable": true
          },
          "currentPage": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          },
          "totalItems": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "ReportDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "dateRange": {
            "$ref": "#/components/schemas/DateRangeDto"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "nullable": true
          },
          "type": {
            "enum": ["Workspace", "User"],
            "type": "string"
          },
          "status": {
            "enum": [
              "Scheduled",
              "InProgress",
              "Completed",
              "Failed",
              "CompletedEmpty",
              "CompletedWithErrors"
            ],
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "dataMaxPrecision": {
            "type": "boolean"
          },
          "version": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "ReportsDto": {
        "type": "object",
        "properties": {
          "reports": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportDto"
            },
            "nullable": true
          },
          "totalItems": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "pageNumber": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "pageSize": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "description": "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ],
  "tags": [
    {
      "name": "Metadata"
    },
    {
      "name": "Reports"
    }
  ]
}
