featurebase-node 0.14.3 → 0.15.1

package/resources/reports.d.ts

@@ -6,6 +6,45 @@ import { RequestOptions } from "../internal/request-options.js";
  * 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 declare 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>;
     /**
      * Returns the reporting catalog: every dataset available to your workspace with
      * its metrics and attributes.
@@ -36,6 +75,37 @@ export declare class Reports extends APIResource {
      * ```
      */
     listDatasets(params?: ReportListDatasetsParams | null | undefined, options?: RequestOptions): APIPromise<ReportListDatasetsResponse>;
+    /**
+     * 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>;
     /**
      * Executes an ad-hoc reporting query: one metric + aggregation over a date range,
      * with optional filters, grouping, segmentation and period-over-period comparison.
@@ -48,7 +118,7 @@ export declare 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
@@ -65,14 +135,19 @@ export declare 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
@@ -91,7 +166,7 @@ export declare 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",
@@ -131,79 +206,11 @@ export declare class Reports extends APIResource {
      *   endDate: '2026-07-15',
      *   granularity: 'day',
      *   metric: 'new_conversations',
-     *   startDate: '2026-07-12',
+     *   startDate: '2026-07-14',
      * });
      * ```
      */
     query(params: ReportQueryParams, options?: RequestOptions): APIPromise<ReportQueryResponse>;
-    /**
-     * 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>;
-    /**
-     * 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>;
 }
 export interface ReportAttribute {
     /**
@@ -243,6 +250,17 @@ export interface ReportAttribute {
 export interface ReportAttributeOption {
     label: string;
     value: string;
+    presentation?: ReportAttributeOption.Presentation;
+}
+export declare namespace ReportAttributeOption {
+    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 {
     id: string;
@@ -300,17 +318,33 @@ export interface ReportGroupedDatum {
     group: string;
     value: number;
     groupLabel?: string;
+    identity?: ReportGroupedDatum.Identity;
     previousValue?: number;
     segments?: Array<ReportSegmentDatum>;
 }
+export declare namespace ReportGroupedDatum {
+    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.
      */
@@ -329,6 +363,7 @@ export interface ReportMetric {
     supportsPeriodComparison: boolean;
     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
@@ -339,6 +374,8 @@ export interface ReportMetric {
      * 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
@@ -355,12 +392,28 @@ export interface ReportMetric {
      */
     variantLabel?: string;
 }
+export declare namespace ReportMetric {
+    interface Algebra {
+        kind: 'direct_aggregate' | 'pipe_computed_ratio';
+    }
+}
 export interface ReportSegmentDatum {
     segment: string;
     value: number;
+    identity?: ReportSegmentDatum.Identity;
     previousValue?: number;
     segmentLabel?: string;
 }
+export declare namespace ReportSegmentDatum {
+    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).
@@ -453,6 +506,10 @@ export interface ReportListDatasetsResponse {
 export interface ReportLookupFilterValuesResponse {
     data: Array<ReportAttributeOption>;
     object: 'list';
+    lookupContextKey?: string;
+    nextCursor?: string;
+    truncated?: boolean;
+    unavailableSelectedValues?: Array<string>;
 }
 export interface ReportQueryResponse {
     meta: ReportQueryResponse.Meta;
@@ -535,12 +592,25 @@ export declare namespace ReportQueryResponse {
         namespace Row {
             interface Cells {
                 display: string;
+                deltaPercent?: number;
                 denominator?: number;
+                identity?: Cells.Identity;
                 numerator?: number;
+                previousValue?: number;
                 raw?: unknown;
                 sortValue?: string | number | null;
                 value?: unknown;
             }
+            namespace Cells {
+                interface Identity {
+                    id: string;
+                    kind: 'teammate' | 'team' | 'user' | 'company' | 'fibi';
+                    label: string;
+                    avatarUrl?: string;
+                    color?: string;
+                    website?: string;
+                }
+            }
         }
         interface Sort {
             columnId: string;
@@ -555,32 +625,32 @@ export declare namespace ReportQueryResponse {
         namespace SummaryRow {
             interface Cells {
                 display: string;
+                deltaPercent?: number;
                 denominator?: number;
+                identity?: Cells.Identity;
                 numerator?: number;
+                previousValue?: number;
                 raw?: unknown;
                 sortValue?: string | number | null;
                 value?: unknown;
             }
+            namespace Cells {
+                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;
     /**
@@ -588,26 +658,30 @@ 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
      * rules and nested groups. Attribute IDs and their allowed operators come from
@@ -615,61 +689,43 @@ 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
      * data when requested), `hourly_heatmap` buckets by day-of-week × hour-of-day,
@@ -681,7 +737,69 @@ 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 declare 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.
+     */
+    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;
+    }
+    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 {
     /**
@@ -689,14 +807,39 @@ export interface ReportLookupFilterValuesParams {
      * `valueSource: "remote_search"` or static options in the catalog).
      */
     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).
@@ -706,12 +849,18 @@ 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;
     /**
@@ -719,30 +868,26 @@ 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
      * rules and nested groups. Attribute IDs and their allowed operators come from
@@ -750,43 +895,61 @@ 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).
-     */
-    page?: number;
-    /**
-     * Body param: Rows per page (1-200, default 25).
+     * Body param: Percentile (1-100) — required when `aggregation` is `percentile`.
      */
-    pageSize?: number;
+    percentile?: number;
     /**
-     * Body param
+     * Body param: Attribute ID for secondary segmentation within each group or time
+     * bucket.
      */
     segmentBy?: string;
     /**
-     * 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: 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`.
      */
-    selectedMetricId?: string;
+    segmentShowOther?: boolean;
     /**
-     * Body param: Stable metric-row ID selected within the launching chart.
+     * 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`.
      */
-    selectedMetricRowId?: string;
+    segmentTopValuesLimit?: number;
     /**
-     * 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 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`.
+     */
+    topValuesLimit?: number;
     /**
      * 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,
@@ -798,56 +961,9 @@ 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 declare 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.
-     */
-    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;
-    }
-    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 {
-    export { type ReportAttribute as ReportAttribute, type ReportAttributeOption as ReportAttributeOption, type ReportDataset as ReportDataset, type ReportFilterExpression as ReportFilterExpression, type ReportFilterRule as ReportFilterRule, type ReportGroupedDatum as ReportGroupedDatum, type ReportMetric as ReportMetric, type ReportSegmentDatum as ReportSegmentDatum, type ReportTimeSeriesDatum as ReportTimeSeriesDatum, type ReportDrillInResponse as ReportDrillInResponse, type ReportListDatasetsResponse as ReportListDatasetsResponse, type ReportLookupFilterValuesResponse as ReportLookupFilterValuesResponse, type ReportQueryResponse as ReportQueryResponse, type ReportListDatasetsParams as ReportListDatasetsParams, type ReportQueryParams as ReportQueryParams, type ReportLookupFilterValuesParams as ReportLookupFilterValuesParams, type ReportDrillInParams as ReportDrillInParams, };
+    export { type ReportAttribute as ReportAttribute, type ReportAttributeOption as ReportAttributeOption, type ReportDataset as ReportDataset, type ReportFilterExpression as ReportFilterExpression, type ReportFilterRule as ReportFilterRule, type ReportGroupedDatum as ReportGroupedDatum, type ReportMetric as ReportMetric, type ReportSegmentDatum as ReportSegmentDatum, type ReportTimeSeriesDatum as ReportTimeSeriesDatum, type ReportDrillInResponse as ReportDrillInResponse, type ReportListDatasetsResponse as ReportListDatasetsResponse, type ReportLookupFilterValuesResponse as ReportLookupFilterValuesResponse, type ReportQueryResponse as ReportQueryResponse, type ReportDrillInParams as ReportDrillInParams, type ReportListDatasetsParams as ReportListDatasetsParams, type ReportLookupFilterValuesParams as ReportLookupFilterValuesParams, type ReportQueryParams as ReportQueryParams, };
 }
 //# sourceMappingURL=reports.d.ts.map