How do I choose the right report?

Start with GET /api/v1/reports and inspect the major_reports array. Each major report includes when_to_use guidance and use cases so agents can choose the right report family before fetching rows.

Can I fetch raw materialized views directly?

Yes. The Reports API also exposes raw materialized-view names in the reports array, and GET /api/v1/reports/:id accepts either a major alias such as top_advertisers_by_sales or an exact materialized-view name.

Can I test the Reports API in the browser without Postman?

Yes. Use the API Playground on this page to run authenticated GET requests, preview JSON inline, or open the same URLs in a new tab—ideal for quick validation alongside these docs.

How does this work with MCP?

The MCP server publishes list_reports, get_report, and several major-report tools such as get_top_advertisers_by_sales_report, get_deals_summary_report, and get_status_counts_report, plus direct operational report tools like get_status_cards_counts_report and get_network_global_last_sync_ats_report so agents can discover and select the right report without memorizing view names.

Reports API Documentation

Materialized-view-backed JSON reports, major-report selection, and an interactive API playground Materialized-view-backed JSON reports, major-report selection, and an interac...

Reports API

The Reports API exposes the app’s materialized views as JSON reports. It gives agents a curated set of major report aliases for common workflows, while still allowing direct access to the raw materialized-view snapshots when needed for operational and infrastructure-style questions.

This page lists every callable report ID currently published by the app: 151 total, including 25 major aliases and 126 raw materialized-view report IDs.

Agent recommendation: Over MCP, call recommend_report first when the request is phrased in natural language. For direct REST use, call GET /api/v1/reports, choose from major_reports using when_to_use, then fetch rows with GET /api/v1/reports/:id.

API Playground

Click Test to run the request and preview the JSON response inline, or Open to view the endpoint in a new tab. Sign in to enable live testing with your API key.

Action	Method	Endpoint	Description
List report catalog	`GET`	`/api/v1/reports`	Returns major_reports and raw report IDs for your scope.
Fetch a major alias	`GET`	`/api/v1/reports/:id`	Use a major alias (e.g. top_advertisers_by_sales) with optional period and limit.
Fetch raw view	`GET`	`/api/v1/reports/:id`	Pass an exact materialized-view name from the catalog when needed.

GET /api/v1/reports v1

List callable reports for your API key.

Open

GET /api/v1/reports/top_advertisers_by_sales?period=last_90_days&limit=5 v1

Major alias with period and row limit.

Open

How to choose the right report

`network_commissions_summary`

Network Commissions Summary

Use this when the user wants a network-level rollup instead of advertiser-level detail.

`daily_kpi_totals`

Daily KPI Totals

Use this when the user needs a time-series trend line for sales, revenue, or commissions.

`top_advertisers_by_sales`

Top Advertisers By Sales

Use this when the user wants the biggest advertisers or top-performing programs.

`top_advertisers_by_clicks`

Top Advertisers By Clicks

Use this when the user wants the most-clicked advertisers or top click-driving programs.

`top_gaining_advertisers`

Top Gaining Advertisers

Use this when the user is asking which advertisers are growing the fastest.

`top_declining_advertisers`

Top Declining Advertisers

Use this when the user is asking which advertisers are falling off or need attention.

`hot_advertisers`

Hot Advertisers

Use this when the user wants fast-moving advertisers, not just the biggest all-around advertisers.

`recent_deals_top_5`

Recent Deals Top 5

Use this when the user asks for the newest deals rather than advertiser performance.

`status_changes_last_24_hours`

Status Changes Last 24 Hours

Use this when the user is asking about recent approval or rejection changes instead of sales performance.

`advertiser_commission_trends`

Advertiser Commission Trends

Use this when the user wants advertiser trend momentum, not just a leaderboard of totals.

`deals_summary`

Deals Summary

Use this when the user wants a high-level deals snapshot instead of individual deal rows.

`deals_by_country`

Deals By Country

Use this when the user wants to understand geographic deal distribution.

`active_deals_by_country`

Active Deals By Country

Use this when the user wants active deal counts by country without the hidden-versus-visible split.

`network_daily_transaction_totals`

Network Daily Transaction Totals

Use this when the user wants a day-by-day network trend rather than a period summary.

`network_daily_sales_commissions_last_30_days`

Network Daily Sales And Commissions Last 30 Days

Use this when the user wants a recent 30-day network revenue trend instead of broader KPI totals.

`network_status_counts`

Network Status Counts

Use this when the user wants a status mix by network instead of recent status-change events.

`status_counts`

Status Counts

Use this when the user wants a current status snapshot, not a time series of changes.

`status_changes_daily_last_year`

Status Changes Daily Last Year

Use this when the user wants a long-running status-change trend instead of the latest 24-hour activity.

`advertiser_transaction_stats_last_7_days`

Advertiser Transaction Stats Last 7 Days

Use this when the user wants a short-window activity snapshot by advertiser.

`advertiser_transaction_stats_last_30_days`

Advertiser Transaction Stats Last 30 Days

Use this when the user wants a monthly advertiser activity snapshot rather than a trend line.

`commission_drops_week_over_week`

Commission Drops Week Over Week

Use this when the user wants a short-term commission risk view.

`commission_drops_month_over_month`

Commission Drops Month Over Month

Use this when the user wants a medium-term commission risk view.

`commission_drops_year_over_year`

Commission Drops Year Over Year

Use this when the user wants a long-horizon decline comparison against last year.

`commission_rate_drops_week_over_week`

Commission Rate Drops Week Over Week

Use this when the user wants rate deterioration rather than total commission declines.

`commission_rate_drops_month_over_month`

Commission Rate Drops Month Over Month

Use this when the user wants medium-term commission-rate deterioration.

All callable report IDs

Every ID below can be passed to GET /api/v1/reports/:id. Prefer a major alias when one exists; use a raw materialized-view name when you explicitly need that exact snapshot.

Major aliases

ID	Scope	Description
`network_commissions_summary`	all_publishers	Revenue, commissions, and sales counts grouped by network for a selected reporting period.
`daily_kpi_totals`	all_publishers	Day-by-day KPI totals with current-period and previous-period comparisons.
`top_advertisers_by_sales`	all_publishers	Ranked advertiser leaderboard ordered by sales and commission contribution.
`top_advertisers_by_clicks`	all_publishers	Ranked advertiser leaderboard ordered by total clicks.
`top_gaining_advertisers`	all_publishers	Advertisers with the largest positive period-over-period commission changes.
`top_declining_advertisers`	all_publishers	Advertisers with the largest negative period-over-period commission changes.
`hot_advertisers`	global	Momentum-based advertiser leaderboard using recent sales and commission changes.
`recent_deals_top_5`	global	Newest deal arrivals ranked by freshness.
`status_changes_last_24_hours`	global	Recent advertiser status transitions such as applied, approved, rejected, or stopped.
`advertiser_commission_trends`	global	Advertiser-level commission trend snapshot comparing the most recent 30 days against the prior 30 days.
`deals_summary`	global	Summary counts for total, active, expired, exclusive, recent, and soon-to-expire deals.
`deals_by_country`	global	Country-level breakdown of deals, including hidden vs visible counts.
`active_deals_by_country`	global	Country-level breakdown of currently active deals.
`network_daily_transaction_totals`	global	Daily transaction, sales, and commission totals grouped by network.
`network_daily_sales_commissions_last_30_days`	global	Last-30-days daily sales and commission totals grouped by network.
`network_status_counts`	global	Advertiser status counts grouped by network.
`status_counts`	global	Current advertiser counts by status for the publisher portfolio.
`status_changes_daily_last_year`	global	Daily counts of advertiser status changes over the last year.
`advertiser_transaction_stats_last_7_days`	global	Advertiser-level transaction, sales, commission, and average commission-rate stats for the last 7 days.
`advertiser_transaction_stats_last_30_days`	global	Advertiser-level transaction, sales, commission, and average commission-rate stats for the last 30 days.
`commission_drops_week_over_week`	global	Advertisers with the largest week-over-week commission declines.
`commission_drops_month_over_month`	global	Advertisers with the largest month-over-month commission declines.
`commission_drops_year_over_year`	global	Advertisers with the largest year-over-year commission declines.
`commission_rate_drops_week_over_week`	global	Advertisers with the largest week-over-week drops in average commission rate.
`commission_rate_drops_month_over_month`	global	Advertisers with the largest month-over-month drops in average commission rate.

Raw materialized-view report IDs

ID	Scope	Preferred alias
`admin_hot_top_advertisers`	admin	hot_advertisers
`admin_publisher_daily_transaction_totals`	admin	None
`advertiser_commission_trends`	publisher	advertiser_commission_trends
`agency_contacts_by_domain`	agency	None
`daily_kpi_totals_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_all_time_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_last_90_days_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_last_month_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_last_year_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_mtd_all_publishers`	all_publishers	daily_kpi_totals
`daily_kpi_totals_ytd_all_publishers`	all_publishers	daily_kpi_totals
`deal_stats_by_advertiser`	publisher	None
`deal_stats_by_publisher`	publisher	None
`global_recent_deals_top_5`	global	recent_deals_top_5
`hienergy_closed_programs_last_week`	publisher	None
`hienergy_sitemap_top_1000_advertisers`	global	None
`hienergy_top_500_advertisers_all_time`	global	None
`hienergy_top_500_advertisers_by_global_total_sales`	global	None
`hienergy_top_500_advertisers_last_90_days`	global	None
`hienergy_top_500_advertisers_last_month`	global	None
`hienergy_top_500_advertisers_last_year`	global	None
`hienergy_top_500_advertisers_this_month`	global	None
`hienergy_top_500_advertisers_ytd`	global	None
`hienergy_top_500_advertisers_ytd_last_year`	global	None
`network_commissions_summary_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_all_time_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_last_90_days_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_last_month_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_last_year_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_mtd_all_publishers`	all_publishers	network_commissions_summary
`network_commissions_summary_ytd_all_publishers`	all_publishers	network_commissions_summary
`network_global_last_sync_ats`	system	None
`publisher_active_deals_by_country`	publisher	active_deals_by_country
`publisher_advertiser_commission_drops_month_over_month`	publisher	commission_drops_month_over_month
`publisher_advertiser_commission_drops_week_over_week`	publisher	commission_drops_week_over_week
`publisher_advertiser_commission_drops_year_over_year`	publisher	commission_drops_year_over_year
`publisher_advertiser_commission_rate_drops_month_over_month`	publisher	commission_rate_drops_month_over_month
`publisher_advertiser_commission_rate_drops_week_over_week`	publisher	commission_rate_drops_week_over_week
`publisher_advertiser_transaction_stats_last_30_days`	publisher	advertiser_transaction_stats_last_30_days
`publisher_advertiser_transaction_stats_last_7_days`	publisher	advertiser_transaction_stats_last_7_days
`publisher_daily_kpi_totals`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_all_time`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_last_90_days`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_last_month`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_last_year`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_mtd`	publisher	daily_kpi_totals
`publisher_daily_kpi_totals_ytd`	publisher	daily_kpi_totals
`publisher_deals_by_country`	publisher	deals_by_country
`publisher_deals_summary`	publisher	deals_summary
`publisher_hot_top_advertisers`	publisher	hot_advertisers
`publisher_network_commissions_summary`	publisher	network_commissions_summary
`publisher_network_commissions_summary_all_time`	publisher	network_commissions_summary
`publisher_network_commissions_summary_last_90_days`	publisher	network_commissions_summary
`publisher_network_commissions_summary_last_month`	publisher	network_commissions_summary
`publisher_network_commissions_summary_last_year`	publisher	network_commissions_summary
`publisher_network_commissions_summary_mtd`	publisher	network_commissions_summary
`publisher_network_commissions_summary_ytd`	publisher	network_commissions_summary
`publisher_network_daily_sales_commissions_last_2_years`	publisher	None
`publisher_network_daily_sales_commissions_last_30_days`	publisher	network_daily_sales_commissions_last_30_days
`publisher_network_daily_sales_commissions_last_year`	publisher	None
`publisher_network_daily_transaction_totals`	publisher	network_daily_transaction_totals
`publisher_network_last_sync_ats`	publisher	None
`publisher_network_status_counts`	publisher	network_status_counts
`publisher_recent_deals_top_5`	publisher	recent_deals_top_5
`publisher_status_changes_daily_last_year`	publisher	status_changes_daily_last_year
`publisher_status_changes_last_24_hours`	publisher	status_changes_last_24_hours
`publisher_status_counts`	publisher	status_counts
`publisher_tag_commission_revenue_top_500_last_year`	publisher	None
`publisher_top_advertisers_by_clicks`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_all_time`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_last_90_days`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_last_month`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_last_year`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_mtd`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_clicks_ytd`	publisher	top_advertisers_by_clicks
`publisher_top_advertisers_by_sales`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_all_time`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_last_90_days`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_last_month`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_last_year`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_mtd`	publisher	top_advertisers_by_sales
`publisher_top_advertisers_by_sales_ytd`	publisher	top_advertisers_by_sales
`publisher_top_declining_advertisers`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_all_time`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_last_90_days`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_last_month`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_last_year`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_mtd`	publisher	top_declining_advertisers
`publisher_top_declining_advertisers_ytd`	publisher	top_declining_advertisers
`publisher_top_gaining_advertisers`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_all_time`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_last_90_days`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_last_month`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_last_year`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_mtd`	publisher	top_gaining_advertisers
`publisher_top_gaining_advertisers_ytd`	publisher	top_gaining_advertisers
`publishers_with_transactions`	publisher	None
`status_cards_counts`	publisher	None
`top_advertisers_by_clicks_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_all_time_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_last_90_days_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_last_month_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_last_year_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_mtd_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_clicks_ytd_all_publishers`	all_publishers	top_advertisers_by_clicks
`top_advertisers_by_sales_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_all_time_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_last_90_days_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_last_month_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_last_year_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_mtd_all_publishers`	all_publishers	top_advertisers_by_sales
`top_advertisers_by_sales_ytd_all_publishers`	all_publishers	top_advertisers_by_sales
`top_declining_advertisers_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_all_time_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_last_90_days_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_last_month_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_last_year_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_mtd_all_publishers`	all_publishers	top_declining_advertisers
`top_declining_advertisers_ytd_all_publishers`	all_publishers	top_declining_advertisers
`top_gaining_advertisers_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_all_time_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_last_90_days_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_last_month_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_last_year_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_mtd_all_publishers`	all_publishers	top_gaining_advertisers
`top_gaining_advertisers_ytd_all_publishers`	all_publishers	top_gaining_advertisers

Endpoints

`GET /api/v1/reports`

Returns major_reports for agent-friendly selection plus the accessible raw materialized views in reports.

`GET /api/v1/reports/:id`

Accepts either a major alias such as top_advertisers_by_sales or an exact materialized-view name.

Optional query params: period for period-based aliases, publisher_id for admin overrides, and limit to cap rows.

MCP workflow for agents

The MCP server exposes recommend_report, list_reports, get_report, and major-report tools like get_top_advertisers_by_sales_report, get_deals_summary_report, get_status_counts_report, and get_network_daily_transaction_totals_report. It also exposes direct operational report tools such as get_status_cards_counts_report, get_network_global_last_sync_ats_report, get_publisher_network_last_sync_ats_report, get_publishers_with_transactions_report, and get_sitemap_top_advertisers_report. Agents should start with recommend_report whenever the user intent is phrased in natural language or the exact report family is ambiguous.

Recommended sequence: recommend_report → call the suggested named MCP tool → fall back to list_reports when you need the full catalog or raw view ids.

Examples

List reports

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/reports"

Fetch a major alias

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/reports/top_advertisers_by_sales?period=last_90_days&limit=25"

Fetch a raw materialized view

curl -H "X-Api-Key: YOUR_KEY" \
  "https://app.hienergy.ai/api/v1/reports/publisher_hot_top_advertisers?limit=25"

Reports API Documentation

Reports API

API Playground

How to choose the right report

network_commissions_summary

daily_kpi_totals

top_advertisers_by_sales

top_advertisers_by_clicks

top_gaining_advertisers

top_declining_advertisers

hot_advertisers

recent_deals_top_5

status_changes_last_24_hours

advertiser_commission_trends

deals_summary

deals_by_country

active_deals_by_country

network_daily_transaction_totals

network_daily_sales_commissions_last_30_days

network_status_counts

status_counts

status_changes_daily_last_year

advertiser_transaction_stats_last_7_days

advertiser_transaction_stats_last_30_days

commission_drops_week_over_week

commission_drops_month_over_month

commission_drops_year_over_year

commission_rate_drops_week_over_week

commission_rate_drops_month_over_month