featurebase-node 0.14.2 → 0.15.0

package/src/resources/reports.ts

@@ -10,6 +10,58 @@ import { RequestOptions } from '../internal/request-options';
  * Query your workspace analytics: conversation volume, response times, CSAT, SLA compliance, teammate performance, AI agent resolutions and more. Start with the datasets catalog to discover metrics and attributes, then run queries with filters, grouping and period comparison.
  */
 export class Reports extends APIResource {
+  /**
+   * Returns the paginated row-level records behind a metric — either the whole
+   * reporting window, or one specific data point from a previous
+   * `POST /v2/reports/query` response.
+   *
+   * Send the **same** `metric`, date range, `granularity`, `filters`, `groupBy` /
+   * `segmentBy` and `view` as the query you're drilling into, plus
+   * `dataPointFilters` selecting the data point:
+   *
+   * - `timeBucket` — a `date` from the time series
+   * - `groupValue` / `segmentValue` — a `group` / `segment` value from grouped data
+   * - `dayOfWeek` + `hourOfDay` — a heatmap cell (`hourly_heatmap` view)
+   * - `flowPathId` or `sourceNodeId` + `targetNodeId` — a flow edge (`sankey` view)
+   *
+   * Pass `dataPointFilters: {}` to list all rows behind the metric for the window.
+   *
+   * Results are paginated with `page` / `pageSize` (max 200 per page);
+   * `availableColumns` describes every column the dataset can return and
+   * `defaultColumnIds` the recommended subset. Rows are keyed by column ID; identity
+   * cells (teammates, contacts) are objects with `id` + `label`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.drillIn({
+   *   endDate: '2026-07-15',
+   *   granularity: 'day',
+   *   metric: 'new_conversations',
+   *   startDate: '2026-07-14',
+   * });
+   * ```
+   */
+  drillIn(params: ReportDrillInParams, options?: RequestOptions): APIPromise<ReportDrillInResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/reports/drill-in', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Returns the reporting catalog: every dataset available to your workspace with
    * its metrics and attributes.
@@ -57,6 +109,55 @@ export class Reports extends APIResource {
     });
   }
 
+  /**
+   * Returns the available values for a filterable attribute — use it to build valid
+   * `filters` rules for `POST /v2/reports/query`.
+   *
+   * Works for attributes whose values live in your workspace data (tags, teammates,
+   * teams, companies, plans, countries, ...). Attributes with `staticOptions` in the
+   * catalog don't need this endpoint — their value set is already inline.
+   *
+   * - `query` narrows results by search string
+   * - `selectedValues` resolves labels for values you already hold (returned
+   *   alongside search results)
+   *
+   * ### Example
+   *
+   * ```json
+   * { "fieldId": "conversation.tags", "query": "bill", "limit": 20 }
+   * ```
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer, and
+   * only for workspaces with the Reports product enabled (404 otherwise).
+   *
+   * @example
+   * ```ts
+   * const response = await client.reports.lookupFilterValues({
+   *   fieldId: 'conversation.tags',
+   * });
+   * ```
+   */
+  lookupFilterValues(
+    params: ReportLookupFilterValuesParams,
+    options?: RequestOptions,
+  ): APIPromise<ReportLookupFilterValuesResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post('/v2/reports/filter-values', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Executes an ad-hoc reporting query: one metric + aggregation over a date range,
    * with optional filters, grouping, segmentation and period-over-period comparison.
@@ -69,7 +170,7 @@ export class Reports extends APIResource {
    *    `percentile: 95` for p95); rate metrics use `value`.
    * 2. Set the reporting window with `startDate` / `endDate` (ISO 8601) and a
    *    `granularity` (`hour`, `day`, `week`, `month`) for the returned time series.
-   *    Reporting data is available from **July 12, 2026**. Windows ending earlier
+   *    Reporting data is available from **July 14, 2026**. Windows ending earlier
    *    are rejected; crossing windows are clamped to that boundary in the requested
    *    timezone.
    * 3. Optionally narrow with `filters` — a rule
@@ -81,13 +182,38 @@ export class Reports extends APIResource {
    * 5. Optionally pass `compareStartDate` / `compareEndDate` to get `previousValue`
    *    / `deltaPercent` alongside every data point.
    *
+   * ### Top-N and Show Other
+   *
+   * For high-cardinality breakdowns, cap the number of returned series:
+   *
+   * - `topValuesLimit` keeps only the top **N** `groupBy` values;
+   *   `segmentTopValuesLimit` does the same for `segmentBy`. Allowed values: **5, 7,
+   *   10, 15, 20**. `topValuesLimit` requires `groupBy`; `segmentTopValuesLimit`
+   *   requires `segmentBy`.
+   * - Members are ranked by the selected metric/aggregation over the **full filtered
+   *   primary range**, so the ranked set is **stable across every time bucket** (a
+   *   value that spikes in one bucket but is small overall does not enter the set).
+   *   A comparison period reuses the **primary period's** ranked set — it is never
+   *   re-ranked, so the legend stays identical period-over-period.
+   * - `showOther` / `segmentShowOther` append a single synthetic bucket with id
+   *   `__other__` and label `Other` that sums every value outside the top set.
+   *   Because the values are summed, Show Other is only supported for **additive
+   *   aggregations** (`count`, `sum`, `value`); it is rejected for `avg`, `median`,
+   *   `min`, `max`, `range`, `percentile`, and for percentage metrics (whose ratios
+   *   cannot be summed). `showOther` also requires `topValuesLimit` (and
+   *   `segmentShowOther` requires `segmentTopValuesLimit`). Plain `topValuesLimit`
+   *   (without Show Other) works with any aggregation.
+   * - The `__other__` group/segment aggregates rows outside the selected top groups
+   *   and **cannot be drilled into** (`POST /v2/reports/drill-in` rejects
+   *   `dataPointFilters.groupValue` / `segmentValue` equal to `__other__`).
+   *
    * ### Example
    *
    * ```json
    * {
    *   "metric": "new_conversations",
    *   "aggregation": "count",
-   *   "startDate": "2026-07-12",
+   *   "startDate": "2026-07-14",
    *   "endDate": "2026-07-15",
    *   "granularity": "day",
    *   "groupBy": "conversation.channel",
@@ -127,7 +253,7 @@ export class Reports extends APIResource {
    *   endDate: '2026-07-15',
    *   granularity: 'day',
    *   metric: 'new_conversations',
-   *   startDate: '2026-07-12',
+   *   startDate: '2026-07-14',
    * });
    * ```
    */
@@ -146,107 +272,6 @@ export class Reports extends APIResource {
       ]),
     });
   }
-
-  /**
-   * Returns the available values for a filterable attribute — use it to build valid
-   * `filters` rules for `POST /v2/reports/query`.
-   *
-   * Works for attributes whose values live in your workspace data (tags, teammates,
-   * teams, companies, plans, countries, ...). Attributes with `staticOptions` in the
-   * catalog don't need this endpoint — their value set is already inline.
-   *
-   * - `query` narrows results by search string
-   * - `selectedValues` resolves labels for values you already hold (returned
-   *   alongside search results)
-   *
-   * ### Example
-   *
-   * ```json
-   * { "fieldId": "conversation.tags", "query": "bill", "limit": 20 }
-   * ```
-   *
-   * ### Version Availability
-   *
-   * This endpoint is only available in API version 2026-01-01.nova and newer, and
-   * only for workspaces with the Reports product enabled (404 otherwise).
-   *
-   * @example
-   * ```ts
-   * const response = await client.reports.lookupFilterValues({
-   *   fieldId: 'conversation.tags',
-   * });
-   * ```
-   */
-  lookupFilterValues(
-    params: ReportLookupFilterValuesParams,
-    options?: RequestOptions,
-  ): APIPromise<ReportLookupFilterValuesResponse> {
-    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-    return this._client.post('/v2/reports/filter-values', {
-      body,
-      ...options,
-      headers: buildHeaders([
-        {
-          ...(featurebaseVersion?.toString() != null ?
-            { 'Featurebase-Version': featurebaseVersion?.toString() }
-          : undefined),
-        },
-        options?.headers,
-      ]),
-    });
-  }
-
-  /**
-   * Returns the paginated row-level records behind a metric — either the whole
-   * reporting window, or one specific data point from a previous
-   * `POST /v2/reports/query` response.
-   *
-   * Send the **same** `metric`, date range, `granularity`, `filters`, `groupBy` /
-   * `segmentBy` and `view` as the query you're drilling into, plus
-   * `dataPointFilters` selecting the data point:
-   *
-   * - `timeBucket` — a `date` from the time series
-   * - `groupValue` / `segmentValue` — a `group` / `segment` value from grouped data
-   * - `dayOfWeek` + `hourOfDay` — a heatmap cell (`hourly_heatmap` view)
-   * - `flowPathId` or `sourceNodeId` + `targetNodeId` — a flow edge (`sankey` view)
-   *
-   * Pass `dataPointFilters: {}` to list all rows behind the metric for the window.
-   *
-   * Results are paginated with `page` / `pageSize` (max 200 per page);
-   * `availableColumns` describes every column the dataset can return and
-   * `defaultColumnIds` the recommended subset. Rows are keyed by column ID; identity
-   * cells (teammates, contacts) are objects with `id` + `label`.
-   *
-   * ### Version Availability
-   *
-   * This endpoint is only available in API version 2026-01-01.nova and newer, and
-   * only for workspaces with the Reports product enabled (404 otherwise).
-   *
-   * @example
-   * ```ts
-   * const response = await client.reports.drillIn({
-   *   endDate: 'xxxxxxxxxx',
-   *   granularity: 'day',
-   *   metric: 'new_conversations',
-   *   startDate: 'xxxxxxxxxx',
-   * });
-   * ```
-   */
-  drillIn(params: ReportDrillInParams, options?: RequestOptions): APIPromise<ReportDrillInResponse> {
-    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
-    return this._client.post('/v2/reports/drill-in', {
-      body,
-      ...options,
-      headers: buildHeaders([
-        {
-          ...(featurebaseVersion?.toString() != null ?
-            { 'Featurebase-Version': featurebaseVersion?.toString() }
-          : undefined),
-        },
-        options?.headers,
-      ]),
-    });
-  }
 }
 
 export interface ReportAttribute {
@@ -414,14 +439,22 @@ export interface ReportMetric {
    */
   id: string;
 
+  algebra: ReportMetric.Algebra;
+
   allowedAggregations: Array<
     'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value'
   >;
 
   description: string;
 
+  executionKind: 'pipe_aggregate' | 'pipe_computed_ratio';
+
   name: string;
 
+  presentationFamily: 'count' | 'duration' | 'percentage' | 'decimal' | 'fibi' | 'ai';
+
+  releaseState: 'available' | 'unavailable';
+
   /**
    * Attribute IDs this specific metric accepts in filter expressions.
    */
@@ -446,6 +479,48 @@ export interface ReportMetric {
   type: 'count' | 'percentage' | 'duration' | 'number';
 
   unit: 'count' | 'percentage' | 'duration_ms' | 'number';
+
+  availabilityReason?: string;
+
+  /**
+   * Local calendar date (ISO 8601) from which this specific metric has data, when it
+   * differs from the global reporting floor. Windows ending before this date are
+   * rejected for this metric.
+   */
+  dataAvailableFromIso?: string;
+
+  /**
+   * Whether this variant is the default selection for its `variantGroupId`.
+   */
+  isDefaultVariant?: boolean;
+
+  qualifiers?: Array<string>;
+
+  searchAliases?: Array<string>;
+
+  /**
+   * Metrics sharing a `variantGroupId` are timestamp variants of one logical metric
+   * (same display `name`); each measures the same population at a different
+   * timestamp. Query the concrete metric `id` to pick a variant.
+   */
+  variantGroupId?: string;
+
+  /**
+   * Stable identifier for this variant within its group (e.g. `created_at`,
+   * `started_at`).
+   */
+  variantId?: string;
+
+  /**
+   * Human-readable variant label for pickers (e.g. `Created at`, `Started at`).
+   */
+  variantLabel?: string;
+}
+
+export namespace ReportMetric {
+  export interface Algebra {
+    kind: 'direct_aggregate' | 'pipe_computed_ratio';
+  }
 }
 
 export interface ReportSegmentDatum {
@@ -497,6 +572,7 @@ export interface ReportDrillInResponse {
       | boolean
       | Array<string>
       | ReportDrillInResponse.ReportDrillInIdentityCell
+      | ReportDrillInResponse.ReportDrillInSourceDetailsCell
       | null;
   }>;
 
@@ -514,6 +590,11 @@ export namespace ReportDrillInResponse {
 
     name: string;
 
+    /**
+     * Whether this column may be used in the drill-in sort request.
+     */
+    supportsSort: boolean;
+
     valueType: string;
 
     category?: string;
@@ -523,6 +604,43 @@ export namespace ReportDrillInResponse {
     datasetId: string;
 
     metricId: string;
+
+    rawMetricId: string;
+
+    reconciliation: Meta.Reconciliation;
+
+    rowGrain: string;
+
+    rowSemantics: 'metric_rows' | 'numerator_rows';
+
+    sourceFact: string;
+
+    emptyReason?: 'no_matching_rows' | 'denominator_unavailable';
+
+    metricRowId?: string;
+  }
+
+  export namespace Meta {
+    export interface Reconciliation {
+      kind:
+        | 'rows'
+        | 'actions_across_conversations'
+        | 'active_hour_rate'
+        | 'positive_ratings_over_eligible_ratings'
+        | 'missed_over_evaluated';
+
+      rowCount: number;
+
+      status: 'not_applicable' | 'available' | 'denominator_unavailable';
+
+      denominatorHours?: number;
+
+      displayedRate?: number;
+
+      eligibleDenominatorTotal?: number;
+
+      rawNumeratorTotal?: number;
+    }
   }
 
   export interface ReportDrillInIdentityCell {
@@ -535,21 +653,45 @@ export namespace ReportDrillInResponse {
     avatarUrl?: string;
 
     color?: string;
+
+    provenance?: 'current' | 'historical' | 'fallback' | 'unassigned';
   }
-}
 
-export interface ReportListDatasetsResponse {
-  data: Array<ReportDataset>;
+  export interface ReportDrillInSourceDetailsCell {
+    items: Array<ReportDrillInSourceDetailsCell.Item>;
 
-  object: 'list';
-}
+    kind: 'source_details';
+  }
 
-export interface ReportLookupFilterValuesResponse {
-  data: Array<ReportAttributeOption>;
+  export namespace ReportDrillInSourceDetailsCell {
+    export interface Item {
+      label: string;
+
+      id?: string;
+
+      type?: string;
+
+      url?: string;
+    }
+  }
+}
+
+export interface ReportListDatasetsResponse {
+  data: Array<ReportDataset>;
 
   object: 'list';
 }
 
+export interface ReportLookupFilterValuesResponse {
+  data: Array<ReportAttributeOption>;
+
+  object: 'list';
+
+  nextCursor?: string;
+
+  unavailableSelectedValues?: Array<string>;
+}
+
 export interface ReportQueryResponse {
   meta: ReportQueryResponse.Meta;
 
@@ -720,25 +862,10 @@ export namespace ReportQueryResponse {
   }
 }
 
-export interface ReportListDatasetsParams {
-  /**
-   * API version for this request. Defaults to your organization's configured API
-   * version if not specified.
-   */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
-
-export interface ReportQueryParams {
-  /**
-   * Body param: Aggregation function applied to the metric. Each metric supports a
-   * subset of aggregations — see the `allowedAggregations` field in the
-   * `GET /v2/reports/datasets` catalog.
-   */
-  aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value';
-
+export interface ReportDrillInParams {
   /**
    * Body param: End of the reporting window (ISO 8601 date or datetime, inclusive).
-   * Windows ending before 2026-07-12 are rejected.
+   * Windows ending before 2026-07-14 are rejected.
    */
   endDate: string;
 
@@ -748,29 +875,34 @@ export interface ReportQueryParams {
   granularity: 'hour' | 'day' | 'week' | 'month';
 
   /**
-   * Body param: Metric ID to query (e.g. `new_conversations`). Discover metric IDs
-   * via `GET /v2/reports/datasets`.
+   * Body param: Metric ID the drill-in belongs to.
    */
   metric: string;
 
   /**
    * Body param: Start of the reporting window (ISO 8601 date or datetime,
-   * inclusive). Reporting data is available from 2026-07-12; crossing windows are
+   * inclusive). Reporting data is available from 2026-07-14; crossing windows are
    * clamped to that boundary.
    */
   startDate: string;
 
   /**
-   * Body param: End of the comparison window. Must be paired with
-   * `compareStartDate`.
+   * Body param: Stable editor ID of the saved chart that launched this drill-in.
    */
-  compareEndDate?: string;
+  chartEditorId?: string;
 
   /**
-   * Body param: Start of the comparison window for period-over-period deltas. Must
-   * be paired with `compareEndDate`.
+   * Body param: Column IDs to include in each returned row. Omit for legacy
+   * full-width static rows; pass an empty array to use `defaultColumnIds`.
    */
-  compareStartDate?: string;
+  columns?: Array<string>;
+
+  /**
+   * Body param: Narrows the drill-in to one data point from a previous query (time
+   * bucket, group value, heatmap cell, or flow edge). Pass `{}` to list all
+   * underlying rows.
+   */
+  dataPointFilters?: ReportDrillInParams.DataPointFilters;
 
   /**
    * Body param: Filter expression: a single rule, or an `and`/`or` group combining
@@ -780,31 +912,49 @@ export interface ReportQueryParams {
   filters?: ReportFilterRule | ReportFilterExpression;
 
   /**
-   * Body param: Attribute ID to group results by (e.g. `conversation.channel`). See
-   * `supportsGroupBy` in the catalog.
+   * Body param
    */
   groupBy?: string;
 
   /**
-   * Body param: Restrict time-based metrics to configured office hours. Only
-   * supported by some metrics (see `supportsOfficeHours` in the catalog).
+   * Body param
    */
   officeHoursOnly?: boolean;
 
   /**
-   * Body param: Percentile (1-100) — required when `aggregation` is `percentile`.
+   * Body param: Page number (1-based).
    */
-  percentile?: number;
+  page?: number;
 
   /**
-   * Body param: Attribute ID for secondary segmentation within each group or time
-   * bucket.
+   * Body param: Rows per page (1-200, default 25).
+   */
+  pageSize?: number;
+
+  /**
+   * Body param
    */
   segmentBy?: string;
 
   /**
-   * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
-   * to UTC.
+   * Body param: A metric ID from the datasets catalog. Use when the originating
+   * chart aggregates several metrics to pick which one the drill-in follows.
+   * Defaults to `metric`.
+   */
+  selectedMetricId?: string;
+
+  /**
+   * Body param: Stable metric-row ID selected within the launching chart.
+   */
+  selectedMetricRowId?: string;
+
+  /**
+   * Body param
+   */
+  sort?: Array<ReportDrillInParams.Sort>;
+
+  /**
+   * Body param
    */
   timezone?: string;
 
@@ -820,7 +970,72 @@ export interface ReportQueryParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export namespace ReportDrillInParams {
+  /**
+   * Narrows the drill-in to one data point from a previous query (time bucket, group
+   * value, heatmap cell, or flow edge). Pass `{}` to list all underlying rows.
+   */
+  export interface DataPointFilters {
+    /**
+     * Day of week (1 = Monday … 7 = Sunday) — for `hourly_heatmap` views.
+     */
+    dayOfWeek?: number;
+
+    /**
+     * Flow path ID — for `sankey` views.
+     */
+    flowPathId?: string;
+
+    /**
+     * Group value to drill into (a `group` value from `groupedData`).
+     */
+    groupValue?: string;
+
+    /**
+     * Hour of day (0-23) — for `hourly_heatmap` views.
+     */
+    hourOfDay?: number;
+
+    /**
+     * Segment value to drill into (a `segment` value from segment data).
+     */
+    segmentValue?: string;
+
+    /**
+     * Flow source node ID — for `sankey` views.
+     */
+    sourceNodeId?: string;
+
+    /**
+     * Flow target node ID — for `sankey` views.
+     */
+    targetNodeId?: string;
+
+    /**
+     * Time bucket to drill into (a `date` value from the query time series).
+     */
+    timeBucket?: string;
+  }
+
+  export interface Sort {
+    direction: 'asc' | 'desc';
+
+    /**
+     * Column ID to sort by (an attribute ID or `metric.value`).
+     */
+    fieldId: string;
+  }
+}
+
+export interface ReportListDatasetsParams {
+  /**
+   * API version for this request. Defaults to your organization's configured API
+   * version if not specified.
+   */
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export interface ReportLookupFilterValuesParams {
@@ -830,16 +1045,41 @@ export interface ReportLookupFilterValuesParams {
    */
   fieldId: string;
 
+  /**
+   * Body param
+   */
+  cursor?: string;
+
+  /**
+   * Body param
+   */
+  datasetId?: string;
+
+  /**
+   * Body param
+   */
+  groupBy?: string;
+
   /**
    * Body param: Maximum number of options to return (1-50, default 20).
    */
   limit?: number;
 
+  /**
+   * Body param
+   */
+  metricId?: string;
+
   /**
    * Body param: Optional search string to narrow the returned options.
    */
   query?: string;
 
+  /**
+   * Body param
+   */
+  segmentBy?: string;
+
   /**
    * Body param: Already-selected values to resolve labels for (returned alongside
    * search results).
@@ -850,12 +1090,20 @@ export interface ReportLookupFilterValuesParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
 }
 
-export interface ReportDrillInParams {
+export interface ReportQueryParams {
   /**
-   * Body param
+   * Body param: Aggregation function applied to the metric. Each metric supports a
+   * subset of aggregations — see the `allowedAggregations` field in the
+   * `GET /v2/reports/datasets` catalog.
+   */
+  aggregation: 'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value';
+
+  /**
+   * Body param: End of the reporting window (ISO 8601 date or datetime, inclusive).
+   * Windows ending before 2026-07-14 are rejected.
    */
   endDate: string;
 
@@ -865,21 +1113,29 @@ export interface ReportDrillInParams {
   granularity: 'hour' | 'day' | 'week' | 'month';
 
   /**
-   * Body param: Metric ID the drill-in belongs to.
+   * Body param: Metric ID to query (e.g. `new_conversations`). Discover metric IDs
+   * via `GET /v2/reports/datasets`.
    */
   metric: string;
 
   /**
-   * Body param
+   * Body param: Start of the reporting window (ISO 8601 date or datetime,
+   * inclusive). Reporting data is available from 2026-07-14; crossing windows are
+   * clamped to that boundary.
    */
   startDate: string;
 
   /**
-   * Body param: Narrows the drill-in to one data point from a previous query (time
-   * bucket, group value, heatmap cell, or flow edge). Pass `{}` to list all
-   * underlying rows.
+   * Body param: End of the comparison window. Must be paired with
+   * `compareStartDate`.
    */
-  dataPointFilters?: ReportDrillInParams.DataPointFilters;
+  compareEndDate?: string;
+
+  /**
+   * Body param: Start of the comparison window for period-over-period deltas. Must
+   * be paired with `compareEndDate`.
+   */
+  compareStartDate?: string;
 
   /**
    * Body param: Filter expression: a single rule, or an `and`/`or` group combining
@@ -889,47 +1145,70 @@ export interface ReportDrillInParams {
   filters?: ReportFilterRule | ReportFilterExpression;
 
   /**
-   * Body param
+   * Body param: Attribute ID to group results by (e.g. `conversation.channel`). See
+   * `supportsGroupBy` in the catalog.
    */
   groupBy?: string;
 
   /**
-   * Body param
+   * Body param: Restrict time-based metrics to configured office hours. Only
+   * supported by some metrics (see `supportsOfficeHours` in the catalog).
    */
   officeHoursOnly?: boolean;
 
   /**
-   * Body param: Page number (1-based).
+   * Body param: Percentile (1-100) — required when `aggregation` is `percentile`.
    */
-  page?: number;
+  percentile?: number;
 
   /**
-   * Body param: Rows per page (1-200, default 25).
+   * Body param: Attribute ID for secondary segmentation within each group or time
+   * bucket.
    */
-  pageSize?: number;
+  segmentBy?: string;
 
   /**
-   * Body param
+   * Body param: When `true`, fold `segmentBy` values outside the top set into a
+   * synthetic `__other__` / `Other` segment. Only supported for additive
+   * aggregations (`count`, `sum`, `value`) and not for percentage metrics. The
+   * `__other__` segment cannot be drilled into. Requires `segmentBy` and
+   * `segmentTopValuesLimit`.
    */
-  segmentBy?: string;
+  segmentShowOther?: boolean;
 
   /**
-   * Body param: A metric ID from the datasets catalog. Use when the originating
-   * chart aggregates several metrics to pick which one the drill-in follows.
-   * Defaults to `metric`.
+   * Body param: Keep only the top N `segmentBy` values per series, ranked by the
+   * selected metric over the full filtered primary range. Under a time View-by the
+   * ranked segment set is identical across every bucket; under a dimension View-by
+   * the ranking is applied within each retained parent group. Allowed values: `5`,
+   * `7`, `10`, `15`, `20`. Requires `segmentBy`.
    */
-  selectedMetricId?: string;
+  segmentTopValuesLimit?: 5 | 7 | 10 | 15 | 20;
 
   /**
-   * Body param
+   * Body param: When `true`, append a single synthetic group with id `__other__` and
+   * label `Other` that sums the values of every `groupBy` value outside the top set.
+   * Only supported for additive aggregations (`count`, `sum`, `value`) and not for
+   * percentage metrics. The `__other__` group cannot be drilled into. Requires
+   * `groupBy` and `topValuesLimit`.
    */
-  sort?: Array<ReportDrillInParams.Sort>;
+  showOther?: boolean;
 
   /**
-   * Body param
+   * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
+   * to UTC.
    */
   timezone?: string;
 
+  /**
+   * Body param: Keep only the top N `groupBy` (View-by) values, ranked by the
+   * selected metric/aggregation over the full filtered primary range. Allowed
+   * values: `5`, `7`, `10`, `15`, `20`. The ranked set is stable across every time
+   * bucket, and a comparison period reuses the primary period's ranked set (never
+   * re-ranked). Requires `groupBy`.
+   */
+  topValuesLimit?: 5 | 7 | 10 | 15 | 20;
+
   /**
    * Body param: Result shape. `standard` returns a time series (plus grouped/segment
    * data when requested), `hourly_heatmap` buckets by day-of-week × hour-of-day,
@@ -942,64 +1221,7 @@ export interface ReportDrillInParams {
    * Header param: API version for this request. Defaults to your organization's
    * configured API version if not specified.
    */
-  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
-}
-
-export namespace ReportDrillInParams {
-  /**
-   * Narrows the drill-in to one data point from a previous query (time bucket, group
-   * value, heatmap cell, or flow edge). Pass `{}` to list all underlying rows.
-   */
-  export interface DataPointFilters {
-    /**
-     * Day of week (1 = Monday … 7 = Sunday) — for `hourly_heatmap` views.
-     */
-    dayOfWeek?: number;
-
-    /**
-     * Flow path ID — for `sankey` views.
-     */
-    flowPathId?: string;
-
-    /**
-     * Group value to drill into (a `group` value from `groupedData`).
-     */
-    groupValue?: string;
-
-    /**
-     * Hour of day (0-23) — for `hourly_heatmap` views.
-     */
-    hourOfDay?: number;
-
-    /**
-     * Segment value to drill into (a `segment` value from segment data).
-     */
-    segmentValue?: string;
-
-    /**
-     * Flow source node ID — for `sankey` views.
-     */
-    sourceNodeId?: string;
-
-    /**
-     * Flow target node ID — for `sankey` views.
-     */
-    targetNodeId?: string;
-
-    /**
-     * Time bucket to drill into (a `date` value from the query time series).
-     */
-    timeBucket?: string;
-  }
-
-  export interface Sort {
-    direction: 'asc' | 'desc';
-
-    /**
-     * Column ID to sort by (an attribute ID or `metric.value`).
-     */
-    fieldId: string;
-  }
+  'Featurebase-Version'?: '2026-08-19.orbit' | '2026-01-01.nova' | '2025-12-12.clover';
 }
 
 export declare namespace Reports {
@@ -1017,9 +1239,9 @@ export declare namespace Reports {
     type ReportListDatasetsResponse as ReportListDatasetsResponse,
     type ReportLookupFilterValuesResponse as ReportLookupFilterValuesResponse,
     type ReportQueryResponse as ReportQueryResponse,
+    type ReportDrillInParams as ReportDrillInParams,
     type ReportListDatasetsParams as ReportListDatasetsParams,
-    type ReportQueryParams as ReportQueryParams,
     type ReportLookupFilterValuesParams as ReportLookupFilterValuesParams,
-    type ReportDrillInParams as ReportDrillInParams,
+    type ReportQueryParams as ReportQueryParams,
   };
 }