UiPath
diff --git a/‎agent_docs/conventions.md‎
Lines changed: 9 additions & 2 deletions b/‎agent_docs/conventions.md‎
Lines changed: 9 additions & 2 deletions
diff --git a/‎docs/oauth-scopes.md‎
Lines changed: 2 additions & 0 deletions b/‎docs/oauth-scopes.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎src/models/maestro/cases.models.ts‎
Lines changed: 87 additions & 16 deletions b/‎src/models/maestro/cases.models.ts‎
Lines changed: 87 additions & 16 deletions
diff --git a/‎src/models/maestro/insights.constants.ts‎
Lines changed: 14 additions & 0 deletions b/‎src/models/maestro/insights.constants.ts‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎src/models/maestro/insights.internal-types.ts‎
Lines changed: 17 additions & 0 deletions b/‎src/models/maestro/insights.internal-types.ts‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎src/models/maestro/insights.types.ts‎
Lines changed: 67 additions & 14 deletions b/‎src/models/maestro/insights.types.ts‎
Lines changed: 67 additions & 14 deletions
@@ -32,8 +32,15 @@
 - **Final response type**: `type {Entity}GetResponse = Raw{Entity}GetResponse & {Entity}Methods` — defined in `*.models.ts`, combining raw data with bound methods.
 - **Options types**: `{Entity}GetAllOptions`, `{Entity}GetByIdOptions`, `{Entity}{Operation}Options` (e.g., `TaskAssignmentOptions`, `ProcessInstanceOperationOptions`). Compose with `RequestOptions & PaginationOptions & { ... }` for list methods.
 - **Common base types**: `BaseOptions` (expand, select), `RequestOptions` (extends BaseOptions with filter, orderby), `OperationResponse<TData>` (success + data) — all from `src/models/common/types.ts`.
-- **Use "Options" not "Request"** for parameter types — the entire SDK uses `{Entity}{Operation}Options`.
-- **Required parameters are always positional; Options objects are reserved for optional parameters only.** Required values (IDs, keys, data) are positional arguments. Options objects are always the last parameter, always marked `?`, and contain only optional fields. E.g., `getOutput(jobKey: string)` not `getOutput(options: { jobKey: string })`, `close(instanceId, folderKey, options?)` not `close(options: { instanceId, folderKey })`.
+- **Parameter type naming — two parallel suffixes:**
+  - `{Entity}{Operation}Options` — bag of **optional** fields. Always the last parameter. Always marked `?`. Contains only optional fields.
+  - `{Entity}{Operation}Request` — bag of **required** fields. Pairs naturally with the existing `{Entity}{Operation}Response`. Convention param name is `request`. Use this **only** when a method has **4+ required values that semantically cluster** (e.g., a process scope + time range). Below that threshold, keep required params positional.
+  - **NEVER** use `Request` as the suffix for an optional-fields bag — that slot is `Options`. The two suffixes are not interchangeable.
+- **Required parameters: positional by default, `Request` object only at 4+.**
+  - 1–3 required params → positional. E.g., `getOutput(jobKey: string)` not `getOutput(options: { jobKey: string })`; `close(instanceId, folderKey, options?)` not `close(options: { instanceId, folderKey })`.
+  - 4+ required params that cluster semantically → single `{Entity}{Operation}Request` object. E.g., `getElementStats(request: ProcessStatsRequest)` where `ProcessStatsRequest` bundles `processKey`, `packageId`, `packageVersion`, `startTime`, `endTime`.
+  - **Shared `Request` type across methods is allowed** when the exact same shape is used by 2+ methods with no natural method-specific anchor — name it after the concept it represents (e.g., `ProcessStatsRequest` is shared by `getElementStats` and `getInstanceStats`). Same rule that already applies to shared response types.
+  - **The same ≤3 / 4+ rule applies to bound entity methods independently.** Bound methods often have fewer required params than their service-level counterparts because the entity auto-fills some fields (e.g., `processKey`, `packageId`). Count what's left after the entity-supplied fields. E.g., service-level `getElementStats` has 5 required → uses `ProcessStatsRequest`. Bound `process.getElementStats(packageVersion, startTime, endTime)` has 3 required → stays positional. The factory delegate constructs the `Request` from the positional args plus the entity's fields before calling the service.
 - **NEVER** duplicate fields across option types — extend existing ones. If `CaseInstanceOperationOptions` already has `comment`, extend it instead of re-declaring. When the shape is identical, use `extends` (e.g., `export interface EntityUpdateRecordByIdOptions extends EntityGetRecordByIdOptions {}`).
 - **Use `Omit` only when a field must not appear in a type at all.** When a field has a server-side default and is simply not required by callers, mark it `?` optional instead. Using `Omit` implies the field would cause an error if included — it misleads callers into thinking they cannot pass the field. Example: if `assignmentCriteria` defaults to `SingleUser` on the server, the options type should declare it as `assignmentCriteria?: TaskAssignmentCriteria`, not `Omit<BaseOptions, 'assignmentCriteria'>`.
 - **Always use `type` for response types** (intersections, unions, composed types). The only place `interface extends` is required is single-type aliases (`type X = Y`), which break TypeDoc — use `export interface EntityUpdateRecordResponse extends EntityRecord {}` instead.
 
@@ -80,6 +80,7 @@ This page lists the specific OAuth scopes required in external app for each SDK
 | `getInstanceStatusTimeline()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 | `getTopExecutionDuration()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 | `getElementStats()` | `Insights.RealTimeData Insights OR.Folders.Read` |
+| `getInstanceStats()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 
 ## Maestro Process Instances
 
@@ -106,6 +107,7 @@ This page lists the specific OAuth scopes required in external app for each SDK
 | `getInstanceStatusTimeline()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 | `getTopExecutionDuration()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 | `getElementStats()` | `Insights.RealTimeData Insights OR.Folders.Read` |
+| `getInstanceStats()` | `Insights.RealTimeData Insights OR.Folders.Read` |
 
 ## Maestro Case Instances
 
 
@@ -4,7 +4,7 @@
  */
 
 import { CaseGetAllResponse, CaseGetTopRunCountResponse, CaseGetTopFaultedCountResponse, CaseGetTopDurationResponse } from './cases.types';
-import { TopQueryOptions, InstanceStatusTimelineResponse, TimelineOptions, ElementGetTopFailedCountResponse, ElementStats } from './insights.types';
+import { TopQueryOptions, InstanceStatusTimelineResponse, TimelineOptions, ElementGetTopFailedCountResponse, ElementStats, InstanceStats, MaestroProcessStatsRequest } from './insights.types';
 
 /**
  * Service for managing UiPath Maestro Cases
@@ -248,31 +248,74 @@ export interface CasesServiceModel {
    * Returns per-element execution counts (success, fail, terminated, paused, in-progress) and
    * duration percentile metrics (min, max, avg, p50, p95, p99) for BPMN elements within a case.
    *
-   * @param processKey - Process key to filter by
-   * @param packageId - Package identifier
-   * @param startTime - Start of the time range to query
-   * @param endTime - End of the time range to query
-   * @param packageVersion - Package version to filter by
+   * @param request - Process scope + time range to aggregate over
    * @returns Promise resolving to an array of {@link ElementStats}
    * @example
    * ```typescript
-   * // Get element metrics for a case
-   * const elements = await cases.getElementStats(
-   *   '<processKey>',
-   *   '<packageId>',
-   *   new Date('2026-04-01'),
-   *   new Date(),
-   *   '1.0.1'
-   * );
+   * // First, list cases to find the processKey, packageId, and available versions
+   * const allCases = await cases.getAll();
+   * const caseItem = allCases[0];
+   *
+   * // Get element metrics for that case
+   * const elements = await cases.getElementStats({
+   *   processKey: caseItem.processKey,
+   *   packageId: caseItem.packageId,
+   *   packageVersion: caseItem.packageVersions[0],
+   *   startTime: new Date('2026-04-01'),
+   *   endTime: new Date(),
+   * });
    *
    * // Find elements with failures
    * const failedElements = elements.filter(e => e.failCount > 0);
    * for (const element of failedElements) {
    *   console.log(`Failed element: ${element.elementId}, failures: ${element.failCount}`);
    * }
+   *
+   * // Using bound method on a case — auto-fills processKey and packageId
+   * const boundElements = await caseItem.getElementStats(
+   *   new Date('2026-04-01'),
+   *   new Date(),
+   *   caseItem.packageVersions[0]
+   * );
    * ```
    */
-  getElementStats(processKey: string, packageId: string, startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
+  getElementStats(request: MaestroProcessStatsRequest): Promise<ElementStats[]>;
+
+  /**
+   * Get instance stats for a case.
+   *
+   * Returns total instance counts broken down by status (running, completed, faulted, etc.)
+   * and the average execution duration for all instances of a case within a time range.
+   *
+   * @param request - Process scope + time range to aggregate over
+   * @returns Promise resolving to {@link InstanceStats}
+   * @example
+   * ```typescript
+   * // First, list cases to find the processKey, packageId, and available versions
+   * const allCases = await cases.getAll();
+   * const caseItem = allCases[0];
+   *
+   * // Get instance status breakdown for that case
+   * const counts = await cases.getInstanceStats({
+   *   processKey: caseItem.processKey,
+   *   packageId: caseItem.packageId,
+   *   packageVersion: caseItem.packageVersions[0],
+   *   startTime: new Date('2026-04-01'),
+   *   endTime: new Date(),
+   * });
+   *
+   * console.log(`Total: ${counts.totalCount}`);
+   * console.log(`Completed: ${counts.completedCount}, Faulted: ${counts.faultedCount}`);
+   *
+   * // Using bound method on a case — auto-fills processKey and packageId
+   * const boundCounts = await caseItem.getInstanceStats(
+   *   new Date('2026-04-01'),
+   *   new Date(),
+   *   caseItem.packageVersions[0]
+   * );
+   * ```
+   */
+  getInstanceStats(request: MaestroProcessStatsRequest): Promise<InstanceStats>;
 }
 
 // Method interface that will be added to case objects
@@ -286,6 +329,16 @@ export interface CaseMethods {
    * @returns Promise resolving to an array of {@link ElementStats}
    */
   getElementStats(startTime: Date, endTime: Date, packageVersion: string): Promise<ElementStats[]>;
+
+  /**
+   * Get instance stats for this case
+   *
+   * @param startTime - Start of the time range to query
+   * @param endTime - End of the time range to query
+   * @param packageVersion - Package version to filter by
+   * @returns Promise resolving to {@link InstanceStats}
+   */
+  getInstanceStats(startTime: Date, endTime: Date, packageVersion: string): Promise<InstanceStats>;
 }
 
 // Combined type for case data with methods
@@ -304,7 +357,25 @@ function createCaseMethods(caseData: CaseGetAllResponse, service: CasesServiceMo
       if (!caseData.processKey) throw new Error('Process key is undefined');
       if (!caseData.packageId) throw new Error('Package ID is undefined');
 
-      return service.getElementStats(caseData.processKey, caseData.packageId, startTime, endTime, packageVersion);
+      return service.getElementStats({
+        processKey: caseData.processKey,
+        packageId: caseData.packageId,
+        packageVersion,
+        startTime,
+        endTime,
+      });
+    },
+    getInstanceStats(startTime: Date, endTime: Date, packageVersion: string): Promise<InstanceStats> {
+      if (!caseData.processKey) throw new Error('Process key is undefined');
+      if (!caseData.packageId) throw new Error('Package ID is undefined');
+
+      return service.getInstanceStats({
+        processKey: caseData.processKey,
+        packageId: caseData.packageId,
+        packageVersion,
+        startTime,
+        endTime,
+      });
     }
   };
 }
 
@@ -0,0 +1,14 @@
+/**
+ * Maps API field names (countOf*) to SDK field names (*Count) for InstanceStats,
+ * aligning naming with ElementStats and other count-suffixed conventions.
+ */
+export const InstanceStatsMap: { [key: string]: string } = {
+  countOfAllInstances: 'totalCount',
+  countOfRunning: 'runningCount',
+  countOfTransitioning: 'transitioningCount',
+  countOfPaused: 'pausedCount',
+  countOfFaulted: 'faultedCount',
+  countOfCompleted: 'completedCount',
+  countOfCancelled: 'cancelledCount',
+  countOfDeleted: 'deletedCount'
+};
@@ -1,3 +1,5 @@
+import { DurationStats } from './insights.types';
+
 /**
  * Raw API response for TopElementswithFailure endpoint.
  * The SDK renames `count` to `failedCount` in the public response type.
@@ -12,3 +14,18 @@ export interface RawElementGetTopFailedCountResponse {
   /** Number of failed executions */
   count: number;
 }
+
+/**
+ * Raw API response for InstanceCountByStatus endpoint.
+ * The SDK renames `countOf*` fields to `*Count` for consistency with ElementStats.
+ */
+export interface RawInstanceStats extends DurationStats {
+  countOfAllInstances: number;
+  countOfRunning: number;
+  countOfTransitioning: number;
+  countOfPaused: number;
+  countOfFaulted: number;
+  countOfCompleted: number;
+  countOfCancelled: number;
+  countOfDeleted: number;
+}
@@ -119,21 +119,12 @@ export interface GetTopDurationResponse extends GetTopBaseResponse {
 }
 
 /**
- * Element count by status for a BPMN element within a process or case
+ * Duration percentile stats shared by Insights aggregate endpoints (per-element and per-process/case).
+ *
+ * For instance-level stats, durations are computed over terminal instances only
+ * (Completed, Cancelled, Deleted) and default to `0` when no terminal instances exist.
  */
-export interface ElementStats {
-  /** BPMN element identifier */
-  elementId: string;
-  /** Number of successful executions */
-  successCount: number;
-  /** Number of failed executions */
-  failCount: number;
-  /** Number of terminated executions */
-  terminatedCount: number;
-  /** Number of paused executions */
-  pausedCount: number;
-  /** Number of in-progress executions */
-  inProgressCount: number;
+export interface DurationStats {
   /** Minimum duration in milliseconds */
   minDurationMs: number;
   /** Maximum duration in milliseconds */
@@ -148,3 +139,65 @@ export interface ElementStats {
   p99DurationMs: number;
 }
 
+/**
+ * Instance count and duration stats aggregated by status for a process or case within a time range.
+ *
+ * Duration fields are computed over terminal instances only (Completed, Cancelled, Deleted)
+ * and default to `0` when no terminal instances exist in the time range.
+ */
+export interface InstanceStats extends DurationStats {
+  /** Total number of instances across all statuses */
+  totalCount: number;
+  /** Number of currently running instances */
+  runningCount: number;
+  /** Number of instances in transitioning state */
+  transitioningCount: number;
+  /** Number of paused instances */
+  pausedCount: number;
+  /** Number of faulted instances */
+  faultedCount: number;
+  /** Number of completed instances */
+  completedCount: number;
+  /** Number of cancelled instances */
+  cancelledCount: number;
+  /** Number of deleted instances */
+  deletedCount: number;
+}
+
+/**
+ * Required request parameters for process-scoped insights stats endpoints
+ * (`getElementStats`, `getInstanceStats`).
+ *
+ * Identifies a single process+package+version and the time range to aggregate over.
+ */
+export interface MaestroProcessStatsRequest {
+  /** Process key to filter by */
+  processKey: string;
+  /** Package identifier */
+  packageId: string;
+  /** Package version to filter by */
+  packageVersion: string;
+  /** Start of the time range to query */
+  startTime: Date;
+  /** End of the time range to query */
+  endTime: Date;
+}
+
+/**
+ * Per-element execution counts and duration percentiles for a BPMN element within a process or case.
+ */
+export interface ElementStats extends DurationStats {
+  /** BPMN element identifier */
+  elementId: string;
+  /** Number of successful executions */
+  successCount: number;
+  /** Number of failed executions */
+  failCount: number;
+  /** Number of terminated executions */
+  terminatedCount: number;
+  /** Number of paused executions */
+  pausedCount: number;
+  /** Number of in-progress executions */
+  inProgressCount: number;
+}
+