featurebase-node 0.14.3 → 0.15.1

package/src/resources/reports.ts

@@ -10,6 +10,60 @@ 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
+   * - `timeSegmentValue` + `timeSegmentGranularity` — the selected bucket from a
+   *   Segment-by-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 +111,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 +172,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
@@ -86,14 +189,19 @@ export class Reports extends APIResource {
    * 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.
+   *   `segmentTopValuesLimit` does the same for `segmentBy`. Both accept integers
+   *   from **1 to 100**; the editor offers common presets plus a Custom value.
+   *   `topValuesLimit` requires `groupBy`; `segmentTopValuesLimit` requires
+   *   `segmentBy`.
+   * - For time-series segment breakdowns, members are ranked **inside each time
+   *   bucket**. The response keeps the union of those bucket winners in its series
+   *   catalog, while a member outside a bucket's Top N has a zero value in that
+   *   bucket. This matches the chart's per-period ranking semantics. A comparison
+   *   period is folded into the primary period's union of visible members so current
+   *   and previous series keep the same identities.
+   * - For non-time-series grouped results, members are ranked over the full filtered
+   *   primary range. A comparison period reuses the primary period's ranked set
+   *   rather than independently changing the legend.
    * - `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
@@ -112,7 +220,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 +260,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 +279,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 {
@@ -339,6 +346,38 @@ export interface ReportAttributeOption {
   label: string;
 
   value: string;
+
+  presentation?: ReportAttributeOption.Presentation;
+}
+
+export namespace ReportAttributeOption {
+  export interface Presentation {
+    kind:
+      | 'brand'
+      | 'company'
+      | 'country'
+      | 'knowledge_source'
+      | 'plain'
+      | 'sla'
+      | 'tag'
+      | 'team'
+      | 'teammate'
+      | 'ticket_category'
+      | 'ticket_state'
+      | 'ticket_type'
+      | 'user'
+      | 'workflow';
+
+    color?: string;
+
+    icon?: unknown;
+
+    iconSvg?: string;
+
+    imageUrl?: string;
+
+    secondaryLabel?: string;
+  }
 }
 
 export interface ReportDataset {
@@ -428,25 +467,53 @@ export interface ReportGroupedDatum {
 
   groupLabel?: string;
 
+  identity?: ReportGroupedDatum.Identity;
+
   previousValue?: number;
 
   segments?: Array<ReportSegmentDatum>;
 }
 
+export namespace ReportGroupedDatum {
+  export interface Identity {
+    id: string;
+
+    kind: 'teammate' | 'team' | 'user' | 'company' | 'fibi';
+
+    label: string;
+
+    avatarUrl?: string;
+
+    color?: string;
+
+    website?: string;
+  }
+}
+
 export interface ReportMetric {
   /**
    * Metric ID — use as `metric` in query requests.
    */
   id: string;
 
+  algebra: ReportMetric.Algebra;
+
   allowedAggregations: Array<
     'count' | 'sum' | 'avg' | 'median' | 'min' | 'max' | 'range' | 'percentile' | 'value'
   >;
 
+  definitionVersion: number;
+
   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 +539,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 +553,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,16 +576,40 @@ export interface ReportMetric {
   variantLabel?: string;
 }
 
+export namespace ReportMetric {
+  export interface Algebra {
+    kind: 'direct_aggregate' | 'pipe_computed_ratio';
+  }
+}
+
 export interface ReportSegmentDatum {
   segment: string;
 
   value: number;
 
+  identity?: ReportSegmentDatum.Identity;
+
   previousValue?: number;
 
   segmentLabel?: string;
 }
 
+export namespace ReportSegmentDatum {
+  export interface Identity {
+    id: string;
+
+    kind: 'teammate' | 'team' | 'user' | 'company' | 'fibi';
+
+    label: string;
+
+    avatarUrl?: string;
+
+    color?: string;
+
+    website?: string;
+  }
+}
+
 export interface ReportTimeSeriesDatum {
   /**
    * Time bucket start (ISO 8601).
@@ -666,6 +763,14 @@ export interface ReportLookupFilterValuesResponse {
   data: Array<ReportAttributeOption>;
 
   object: 'list';
+
+  lookupContextKey?: string;
+
+  nextCursor?: string;
+
+  truncated?: boolean;
+
+  unavailableSelectedValues?: Array<string>;
 }
 
 export interface ReportQueryResponse {
@@ -796,19 +901,41 @@ export namespace ReportQueryResponse {
       export interface Cells {
         display: string;
 
+        deltaPercent?: number;
+
         denominator?: number;
 
+        identity?: Cells.Identity;
+
         numerator?: number;
 
+        previousValue?: number;
+
         raw?: unknown;
 
         sortValue?: string | number | null;
 
         value?: unknown;
       }
-    }
 
-    export interface Sort {
+      export namespace Cells {
+        export interface Identity {
+          id: string;
+
+          kind: 'teammate' | 'team' | 'user' | 'company' | 'fibi';
+
+          label: string;
+
+          avatarUrl?: string;
+
+          color?: string;
+
+          website?: string;
+        }
+      }
+    }
+
+    export interface Sort {
       columnId: string;
 
       direction: 'asc' | 'desc';
@@ -824,39 +951,46 @@ export namespace ReportQueryResponse {
       export interface Cells {
         display: string;
 
+        deltaPercent?: number;
+
         denominator?: number;
 
+        identity?: Cells.Identity;
+
         numerator?: number;
 
+        previousValue?: number;
+
         raw?: unknown;
 
         sortValue?: string | number | null;
 
         value?: unknown;
       }
+
+      export namespace Cells {
+        export interface Identity {
+          id: string;
+
+          kind: 'teammate' | 'team' | 'user' | 'company' | 'fibi';
+
+          label: string;
+
+          avatarUrl?: string;
+
+          color?: string;
+
+          website?: string;
+        }
+      }
     }
   }
 }
 
-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 +1000,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 +1037,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 +1095,82 @@ 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;
+
+    /**
+     * Granularity of `timeSegmentValue`; both fields must be sent together.
+     */
+    timeSegmentGranularity?: 'hour' | 'day' | 'week' | 'month';
+
+    /**
+     * Time-segment bucket selected from a Segment-by-Time series.
+     */
+    timeSegmentValue?: 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 +1180,47 @@ 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: Opaque client context echoed by the response so stale lookup results
+   * can be discarded safely.
+   */
+  lookupContextKey?: string;
+
+  /**
+   * 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 +1231,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 +1254,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 +1286,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. Under a time
+   * View-by, segments are ranked independently inside each time bucket and the
+   * response series catalog contains the union of bucket winners. Under a dimension
+   * View-by, ranking is applied within each retained parent group. Allowed range:
+   * `1` to `100`; the editor offers common presets plus a Custom value. Requires
+   * `segmentBy`.
    */
-  selectedMetricId?: string;
+  segmentTopValuesLimit?: number;
 
   /**
-   * 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 range:
+   * `1` to `100`; the editor offers common presets plus a Custom value. A comparison
+   * period reuses the primary period's ranked set. Requires `groupBy`.
    */
-  timezone?: string;
+  topValuesLimit?: number;
 
   /**
    * Body param: Result shape. `standard` returns a time series (plus grouped/segment
@@ -1115,64 +1362,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 +1380,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,
   };
 }