Build an insights report with AI

---
name: build-insights-report
description: Build a Hyperline billing or revenue insights report. Use when an agent needs to answer reporting questions with read-only API, MCP, or CLI calls across analytics, subscriptions, invoices, customers, and usage data.
---

# Build Insights Report

Default to read-only operations.

## Inputs

Collect these values before querying data:

- Report question: what the user wants to know.
- Timeframe: e.g. current month, previous quarter, last 12 months.
- Environment: production or sandbox.
- Optional filters: customer, plan, product, currency, subscription status, invoice status, or segment.
- Output format: short answer, table, CSV-ready data, or executive summary.

If the timeframe is ambiguous, ask a short clarification before querying.

## Data sources

Start with the narrowest source:

- `GET /v1/analytics` for revenue metrics and high-level KPIs.
- `GET /v2/subscriptions` for subscription lists, statuses, plans, renewal dates, and quote links.
- `GET /v1/invoices` for invoice status, due dates, amounts, and payment health.
- `GET /v2/customers/{id}` or `GET /v2/customers` for customer context.
- Usage endpoints when the question is about usage-based billing or consumption.

Use MCP or CLI equivalents when the user's agent environment already has them configured.

## Workflow

1. Restate the metric definition in one sentence.
2. Query only the data needed for that definition.
3. Use pagination for list endpoints.
4. Keep raw IDs in working notes, but present names and links when available.
5. Separate facts from interpretation.
6. Call out gaps, filters, or assumptions.

## Output

Return:

- Answer first.
- Then a small table when it helps.
- Then methodology: endpoints, filters, and timeframe.
- Then caveats or recommended follow-up.

## Safety

- Do not mutate data.
- Do not infer cash collection from invoice issuance; check payment or transaction status when the question is about cash.
- Do not mix sandbox and production data.
- Do not compare periods with different currencies unless the user asked for a multi-currency view.