Skip to content
Featurebase Featurebase Featurebase
Dashboard
API Reference
Reports

List report datasets

GET/v2/reports/datasets

Returns the reporting catalog: every dataset available to your workspace with its metrics and attributes.

This is the discovery endpoint for the reporting API — read it before building query payloads:

  • Metrics carry the metric IDs accepted by POST /v2/reports/query, plus each metric’s allowedAggregations, unit, and whether it supports office-hours restriction and period comparison.
  • Attributes carry the fieldIds accepted in filter rules and the attribute IDs accepted as groupBy / segmentBy, plus each attribute’s allowedOperators and value type. Attributes with staticOptions list their full value set inline; other filterable attributes resolve values via POST /v2/reports/filter-values.

The catalog includes your workspace’s custom conversation/ticket attributes where applicable, so it can differ between workspaces.

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

Header ParametersExpand Collapse
"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"
One of the following:
"2026-01-01.nova"
"2025-12-12.clover"
ReturnsExpand Collapse
data: array of ReportDataset { id, attributes, description, 2 more }
id: string
attributes: array of ReportAttribute { id, allowedOperators, category, 9 more }
id: string

Attribute ID — use as fieldId in filter rules and as groupBy / segmentBy in query requests.

allowedOperators: array of "is" or "is_not" or "in" or 10 more
One of the following:
"is"
"is_not"
"in"
"not_in"
"contains"
"not_contains"
"gte"
"lte"
"between"
"exists"
"not_exists"
"is_member_of"
"is_not_member_of"
category: string
description: string
name: string
semantics: "current_state" or "historical_action" or "historical_snapshot" or "dynamic_metric_mapped"

Whether the filter uses the latest mutable state, an immutable historical action/snapshot, or a metric-dependent mapping.

One of the following:
"current_state"
"historical_action"
"historical_snapshot"
"dynamic_metric_mapped"
supportsFilter: boolean

Whether the attribute can be used in filters rules.

supportsGroupBy: boolean

Whether the attribute can be used as groupBy / segmentBy.

supportsValueLookup: boolean

Whether POST /v2/reports/filter-values can list this attribute’s values.

valueType: "string" or "number" or "boolean" or 3 more
One of the following:
"string"
"number"
"boolean"
"date"
"enum"
"id"
multiValue: optional boolean
staticOptions: optional array of ReportAttributeOption { label, value }

Fixed value set for enum-like attributes. Attributes without static options resolve values via POST /v2/reports/filter-values.

label: string
value: string
description: string
metrics: array of ReportMetric { id, allowedAggregations, description, 13 more }
id: string

Metric ID — use as metric in query requests.

allowedAggregations: array of "count" or "sum" or "avg" or 6 more
One of the following:
"count"
"sum"
"avg"
"median"
"min"
"max"
"range"
"percentile"
"value"
description: string
name: string
supportedFilterAttributeIds: array of string

Attribute IDs this specific metric accepts in filter expressions.

supportedGroupByDimensions: array of string

Attribute IDs this specific metric accepts as groupBy or segmentBy.

supportedViews: array of "standard" or "hourly_heatmap" or "sankey"

Which view values POST /v2/reports/query accepts for this metric. Most metrics support standard and hourly_heatmap; conversation-flow metrics are sankey-only.

One of the following:
"standard"
"hourly_heatmap"
"sankey"
supportsOfficeHours: boolean
supportsPeriodComparison: boolean
type: "count" or "percentage" or "duration" or "number"
One of the following:
"count"
"percentage"
"duration"
"number"
unit: "count" or "percentage" or "duration_ms" or "number"
One of the following:
"count"
"percentage"
"duration_ms"
"number"
dataAvailableFromIso: optional string

Local calendar date (ISO 8601) from which this specific metric has data, when it differs from the global reporting floor. Windows ending before this date are rejected for this metric.

isDefaultVariant: optional boolean

Whether this variant is the default selection for its variantGroupId.

variantGroupId: optional string

Metrics sharing a variantGroupId are timestamp variants of one logical metric (same display name); each measures the same population at a different timestamp. Query the concrete metric id to pick a variant.

variantId: optional string

Stable identifier for this variant within its group (e.g. created_at, started_at).

variantLabel: optional string

Human-readable variant label for pickers (e.g. Created at, Started at).

name: string
object: "list"

List report datasets

curl https://do.featurebase.app/v2/reports/datasets \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
{
  "data": [
    {
      "id": "conversations",
      "attributes": [
        {
          "id": "conversation.channel",
          "allowedOperators": [
            "in"
          ],
          "category": "conversation",
          "description": "description",
          "name": "Channel",
          "semantics": "current_state",
          "supportsFilter": true,
          "supportsGroupBy": true,
          "supportsValueLookup": true,
          "valueType": "string",
          "multiValue": true,
          "staticOptions": [
            {
              "label": "label",
              "value": "value"
            }
          ]
        }
      ],
      "description": "description",
      "metrics": [
        {
          "id": "new_conversations",
          "allowedAggregations": [
            "count"
          ],
          "description": "description",
          "name": "New conversations",
          "supportedFilterAttributeIds": [
            "string"
          ],
          "supportedGroupByDimensions": [
            "string"
          ],
          "supportedViews": [
            "standard"
          ],
          "supportsOfficeHours": true,
          "supportsPeriodComparison": true,
          "type": "count",
          "unit": "count",
          "dataAvailableFromIso": "2026-07-12",
          "isDefaultVariant": true,
          "variantGroupId": "new_conversations",
          "variantId": "started_at",
          "variantLabel": "Started at"
        }
      ],
      "name": "Conversations"
    }
  ],
  "object": "list"
}
Returns Examples
{
  "data": [
    {
      "id": "conversations",
      "attributes": [
        {
          "id": "conversation.channel",
          "allowedOperators": [
            "in"
          ],
          "category": "conversation",
          "description": "description",
          "name": "Channel",
          "semantics": "current_state",
          "supportsFilter": true,
          "supportsGroupBy": true,
          "supportsValueLookup": true,
          "valueType": "string",
          "multiValue": true,
          "staticOptions": [
            {
              "label": "label",
              "value": "value"
            }
          ]
        }
      ],
      "description": "description",
      "metrics": [
        {
          "id": "new_conversations",
          "allowedAggregations": [
            "count"
          ],
          "description": "description",
          "name": "New conversations",
          "supportedFilterAttributeIds": [
            "string"
          ],
          "supportedGroupByDimensions": [
            "string"
          ],
          "supportedViews": [
            "standard"
          ],
          "supportsOfficeHours": true,
          "supportsPeriodComparison": true,
          "type": "count",
          "unit": "count",
          "dataAvailableFromIso": "2026-07-12",
          "isDefaultVariant": true,
          "variantGroupId": "new_conversations",
          "variantId": "started_at",
          "variantLabel": "Started at"
        }
      ],
      "name": "Conversations"
    }
  ],
  "object": "list"
}