---
title: Reports API overview | Featurebase
description: Query your workspace analytics programmatically – conversation volume, response times, CSAT, SLAs, teammate performance and AI resolutions.
---

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:

Terminal window

```
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:

Terminal window

```
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:

Terminal window

```
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](/guides/reports/query-syntax/index.md) for the full grammar – filters, grouping, comparison windows, heatmaps and flow views.