Reports API overview

The Reports API exposes the same analytics engine that powers the Reports section of the Featurebase dashboard. You can run any query the dashboard can: pick a metric, aggregate it over a date range, filter it, break it down by dimensions, compare periods, and drill into the underlying rows.

All endpoints live under /v2/reports and use your regular API key:

Authorization: Bearer sk_...

Note: The Reports API requires API version 2026-01-01.nova or newer, and is only available for workspaces with the Reports product enabled.

The four endpoints

Endpoint	Purpose
GET /v2/reports/datasets	Discovery – lists every metric and attribute your workspace can query
POST /v2/reports/query	Runs an aggregate query (time series, grouping, comparison)
POST /v2/reports/filter-values	Lists the values available for a filter attribute
POST /v2/reports/drill-in	Returns the row-level records behind a data point

Quickstart

1. Fetch the catalog to see what you can query:

curl https://do.featurebase.app/v2/reports/datasets \
  -H "Authorization: Bearer sk_..."

Each dataset lists its metrics (with allowedAggregations) and attributes (with allowedOperators, filter and group-by support).

2. Run a query – new conversations per day in June, grouped by channel:

curl https://do.featurebase.app/v2/reports/query \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "new_conversations",
    "aggregation": "count",
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "granularity": "day",
    "groupBy": "conversation.channel"
  }'

The response contains the aggregate value, a timeSeries with one datum per day, and groupedData with one entry per channel.

3. Drill into a data point – the conversations behind June 15th:

curl https://do.featurebase.app/v2/reports/drill-in \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "new_conversations",
    "startDate": "2026-06-01",
    "endDate": "2026-06-30",
    "granularity": "day",
    "dataPointFilters": { "timeBucket": "2026-06-15" },
    "page": 1,
    "pageSize": 25
  }'

Using the SDK

The same queries through the Node SDK:

import Featurebase from 'featurebase';

const client = new Featurebase({ apiKey: process.env.FEATUREBASE_API_KEY });

const catalog = await client.reports.listDatasets();

const result = await client.reports.query({
  metric: 'csat_score',
  aggregation: 'value',
  startDate: '2026-06-01',
  endDate: '2026-06-30',
  granularity: 'week',
});

What can you measure?

Metrics span the whole support surface (the catalog is authoritative for your workspace):

• Volume – new_conversations, closed_conversations, open_conversations, tagged_conversations
• Responsiveness – first_response_time_started_excluding_bot, time_to_close_excluding_bot, response_time_reply_sent_at
• Effectiveness – one_touch_resolution_rate, reopen_rate, replies_to_close
• CSAT – csat_score, conversation_ratings, csat_response_rate
• SLAs – applied / hit / missed counts and hit rates
• AI agent (Fibi) – fibi_involved_conversations, fibi_deflection_rate, fibi_resolution_rate, fibi_resolution_time
• Copilot – copilot_questions, copilot_assisted_conversations, copilot_time_saved_estimate
• Teammate performance – replies_sent, conversations_participated, agent_handling_time
• Tickets – volume, time-to-resolve, time-in-state

Duration metrics support avg, median, min, max and percentile aggregations (pass percentile: 95 for p95). Rate metrics use value. Count metrics use count.

Continue with the query syntax reference for the full grammar – filters, grouping, comparison windows, heatmaps and flow views.