Reports

Drill into report rows

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.

POST

/v2/reports/drill-in

curl --request POST \
  --url https://do.featurebase.app/v2/reports/drill-in \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chartEditorId": "<string>",
  "columns": [
    "<string>"
  ],
  "dataPointFilters": {},
  "endDate": "2026-07-15",
  "filters": {
    "fieldId": "conversation.channel",
    "kind": "rule",
    "operator": "in",
    "value": "<string>"
  },
  "granularity": "day",
  "groupBy": "<string>",
  "metric": "new_conversations",
  "officeHoursOnly": false,
  "page": 1,
  "pageSize": 25,
  "segmentBy": "<string>",
  "selectedMetricId": "<string>",
  "selectedMetricRowId": "<string>",
  "sort": [
    {
      "direction": "asc",
      "fieldId": "metric.value"
    }
  ],
  "startDate": "2026-07-14",
  "timezone": "<string>",
  "view": "standard"
}
'

{
  "availableColumns": [
    {
      "category": "<string>",
      "id": "<string>",
      "name": "<string>",
      "supportsSort": true,
      "valueType": "<string>"
    }
  ],
  "defaultColumnIds": [
    "<string>"
  ],
  "meta": {
    "datasetId": "<string>",
    "emptyReason": "no_matching_rows",
    "metricId": "<string>",
    "metricRowId": "<string>",
    "rawMetricId": "<string>",
    "reconciliation": {
      "denominatorHours": 123,
      "displayedRate": 123,
      "eligibleDenominatorTotal": 123,
      "kind": "rows",
      "rawNumeratorTotal": 123,
      "rowCount": 123,
      "status": "not_applicable"
    },
    "rowGrain": "<string>",
    "rowSemantics": "metric_rows",
    "sourceFact": "<string>"
  },
  "object": "report_drill_in_result",
  "page": 123,
  "pageSize": 123,
  "rows": [
    {}
  ],
  "timezone": "<string>",
  "total": 123
}

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).

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Example: 2026-08-19.orbit

Body

chartEditorIdstring

Stable editor ID of the saved chart that launched this drill-in.

Required string length: 1 - 256

columnsstring[]

Column IDs to include in each returned row. Omit for legacy full-width static rows; pass an empty array to use defaultColumnIds.

Maximum array length: 500

dataPointFiltersobjectdefault:{}

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.

Show child attributes

endDatestringrequired

End of the reporting window (ISO 8601 date or datetime, inclusive). Windows ending before 2026-07-14 are rejected.

Required string length: 10 - 64

Example: 2026-07-15

filtersobject

Filter expression: a single rule, or an and/or group combining rules and nested groups. Attribute IDs and their allowed operators come from GET /v2/reports/datasets.

Show child attributes

granularityenum<string>required

Time bucket size for the returned time series.

Available options: hour, day, week, month

Example: day

groupBystring

Maximum string length: 512

metricstringrequired

Metric ID the drill-in belongs to.

Required string length: 1 - 128

Example: new_conversations

officeHoursOnlybooleandefault:false

pageintegerdefault:1

Page number (1-based).

Required range: 1 <= x

pageSizeintegerdefault:25

Rows per page (1-200, default 25).

Required range: 1 <= x <= 200

segmentBystring

Maximum string length: 512

selectedMetricIdstring

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.

Required string length: 1 - 128

selectedMetricRowIdstring

Stable metric-row ID selected within the launching chart.

Required string length: 1 - 256

sortobject[]

Maximum array length: 3

Show child attributes

startDatestringrequired

Start of the reporting window (ISO 8601 date or datetime, inclusive). Reporting data is available from 2026-07-14; crossing windows are clamped to that boundary.

Required string length: 10 - 64

Example: 2026-07-14

timezonestring

Maximum string length: 64

viewenum<string>

Result shape. standard returns a time series (plus grouped/segment data when requested), hourly_heatmap buckets by day-of-week × hour-of-day, sankey returns conversation flow data. Each metric lists its supportedViews in the GET /v2/reports/datasets catalog.

Available options: standard, hourly_heatmap, sankey

Example: standard

Response

Success

availableColumnsobject[]required

Show child attributes

defaultColumnIdsstring[]required

metaobjectrequired

Show child attributes

objectenum<string>required

Available options: report_drill_in_result

pageintegerrequired

pageSizeintegerrequired

rowsobject[]required

One record per underlying row, keyed by column ID.

timezonestringrequired

totalintegerrequired

Still need help? Ask the team