featurebase-node 0.14.3 → 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
@@ -112,7 +213,7 @@ export class Reports extends APIResource {
    * {
    *   "metric": "new_conversations",
    *   "aggregation": "count",
-   *   "startDate": "2026-07-12",
+   *   "startDate": "2026-07-14",
    *   "endDate": "2026-07-15",
    *   "granularity": "day",
    *   "groupBy": "conversation.channel",
@@ -152,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',
    * });
    * ```
    */
@@ -171,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: '2026-07-15',
-   *   granularity: 'day',
-   *   metric: 'new_conversations',
-   *   startDate: '2026-07-12',
-   * });
-   * ```
-   */
-  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 {
@@ -439,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.
    */
@@ -472,6 +480,8 @@ export interface ReportMetric {
 
   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
@@ -484,6 +494,10 @@ export interface ReportMetric {
    */
   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
@@ -503,6 +517,12 @@ export interface ReportMetric {
   variantLabel?: string;
 }
 
+export namespace ReportMetric {
+  export interface Algebra {
+    kind: 'direct_aggregate' | 'pipe_computed_ratio';
+  }
+}
+
 export interface ReportSegmentDatum {
   segment: string;
 
@@ -666,6 +686,10 @@ export interface ReportLookupFilterValuesResponse {
   data: Array<ReportAttributeOption>;
 
   object: 'list';
+
+  nextCursor?: string;
+
+  unavailableSelectedValues?: Array<string>;
 }
 
 export interface ReportQueryResponse {
@@ -838,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;
 
@@ -866,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
@@ -898,69 +912,51 @@ 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).
    */
-  segmentBy?: string;
+  pageSize?: number;
 
   /**
-   * 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`.
+   * Body param
    */
-  segmentShowOther?: boolean;
+  segmentBy?: string;
 
   /**
-   * 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`.
+   * 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`.
    */
-  segmentTopValuesLimit?: 5 | 7 | 10 | 15 | 20;
+  selectedMetricId?: string;
 
   /**
-   * 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`.
+   * Body param: Stable metric-row ID selected within the launching chart.
    */
-  showOther?: boolean;
+  selectedMetricRowId?: string;
 
   /**
-   * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
-   * to UTC.
+   * Body param
    */
-  timezone?: string;
+  sort?: Array<ReportDrillInParams.Sort>;
 
   /**
-   * 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`.
+   * Body param
    */
-  topValuesLimit?: 5 | 7 | 10 | 15 | 20;
+  timezone?: string;
 
   /**
    * Body param: Result shape. `standard` returns a time series (plus grouped/segment
@@ -974,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 {
@@ -984,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).
@@ -1004,13 +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: 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-12 are rejected.
+   * Windows ending before 2026-07-14 are rejected.
    */
   endDate: string;
 
@@ -1020,34 +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: 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: Stable editor ID of the saved chart that launched this drill-in.
-   */
-  chartEditorId?: string;
-
-  /**
-   * Body param: Column IDs to include in each returned row. Omit for legacy
-   * full-width static rows; pass an empty array to use `defaultColumnIds`.
+   * Body param: End of the comparison window. Must be paired with
+   * `compareStartDate`.
    */
-  columns?: Array<string>;
+  compareEndDate?: 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: Start of the comparison window for period-over-period deltas. Must
+   * be paired with `compareEndDate`.
    */
-  dataPointFilters?: ReportDrillInParams.DataPointFilters;
+  compareStartDate?: string;
 
   /**
    * Body param: Filter expression: a single rule, or an `and`/`or` group combining
@@ -1057,51 +1145,69 @@ 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: Stable metric-row ID selected within the launching chart.
+   * 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`.
    */
-  selectedMetricRowId?: string;
+  showOther?: boolean;
 
   /**
-   * Body param
+   * Body param: IANA timezone for date bucketing (e.g. `America/New_York`). Defaults
+   * to UTC.
    */
-  sort?: Array<ReportDrillInParams.Sort>;
+  timezone?: string;
 
   /**
-   * Body param
+   * 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`.
    */
-  timezone?: string;
+  topValuesLimit?: 5 | 7 | 10 | 15 | 20;
 
   /**
    * Body param: Result shape. `standard` returns a time series (plus grouped/segment
@@ -1115,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 {
@@ -1190,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,
   };
 }