Skip to content

Reports

The Reports API generates formatted HTML reports for portfolios and individual properties. Reports include cost summaries, usage trends, rate comparisons, and savings recommendations. All endpoints require authentication and are prefixed with /reports.

PDF Export

The HTML reports are print-optimized. Use your browser's print-to-PDF function or a headless browser (e.g., Puppeteer, wkhtmltopdf) to convert them to PDF.

GET /reports/portfolio/{portfolio_id}

Generate a comprehensive portfolio report in HTML format.
Auth required Yes
Response Content-Type text/html

Path Parameters

Parameter Type Description
portfolio_id string Portfolio ID

Query Parameters

Parameter Type Default Description
start_date string 12 months ago Report period start (YYYY-MM-DD)
end_date string Today Report period end (YYYY-MM-DD)
include_savings boolean true Include savings analysis section
include_charts boolean true Include embedded SVG charts

Example Request

curl -o portfolio_report.html \
  "https://app.meterbase.io/api/v1/reports/portfolio/pf_abc123?start_date=2025-04-01&end_date=2026-03-31" \
  -H "Authorization: Bearer $TOKEN"

Example Response

200 OK (Content-Type: text/html)

The response is a self-contained HTML document with inline styles and SVG charts. The report includes the following sections:

Section Contents
Executive Summary Total cost, total usage, property count, savings potential
Cost Trends Month-over-month cost chart across the reporting period
Property Breakdown Per-property cost table with sorting
Rate Analysis Current tariffs and recommended alternatives per property
Savings Opportunities Ranked list of savings actions with projected impact
Appendix Tariff details, methodology notes 
// Note: The actual response is HTML. This shows the conceptual structure.
{
  "report_type": "portfolio",
  "portfolio_name": "West Coast Holdings",
  "period": "2025-04-01 to 2026-03-31",
  "sections": [
    "Executive Summary",
    "Cost Trends",
    "Property Breakdown",
    "Rate Analysis",
    "Savings Opportunities",
    "Appendix"
  ]
}

Error Cases

Status Detail Cause
404 "Portfolio not found" Invalid or inaccessible portfolio ID
400 "end_date must be after start_date" Invalid date range
400 "Report period cannot exceed 5 years" Date range too long

GET /reports/property/{property_id}

Generate a detailed property report in HTML format.
Auth required Yes
Response Content-Type text/html

Path Parameters

Parameter Type Description
property_id string Property ID

Query Parameters

Parameter Type Default Description
start_date string 12 months ago Report period start (YYYY-MM-DD)
end_date string Today Report period end (YYYY-MM-DD)
include_savings boolean true Include savings analysis section
include_charts boolean true Include embedded SVG charts
include_bills boolean true Include individual bill details

Example Request

curl -o property_report.html \
  "https://app.meterbase.io/api/v1/reports/property/prop_abc123?include_bills=true" \
  -H "Authorization: Bearer $TOKEN"

Example Response

200 OK (Content-Type: text/html)

The response is a self-contained HTML document. The report includes the following sections:

Section Contents
Property Overview Address, type, square footage, current tariff, utility
Cost Summary Annual cost, average monthly, cost per kWh, cost per sqft
Usage & Demand Trends Monthly kWh and kW charts
Bill History Table of all bills in the reporting period with line-item details
Rate Analysis Current tariff breakdown with TOU periods and demand rates
Savings Analysis Alternative tariffs ranked by savings with comparison charts
Recommendations Actionable next steps 
// Note: The actual response is HTML. This shows the conceptual structure.
{
  "report_type": "property",
  "property_name": "Sunset Apartments",
  "period": "2025-04-01 to 2026-03-31",
  "sections": [
    "Property Overview",
    "Cost Summary",
    "Usage & Demand Trends",
    "Bill History",
    "Rate Analysis",
    "Savings Analysis",
    "Recommendations"
  ]
}

Error Cases

Status Detail Cause
404 "Property not found" Invalid or inaccessible property ID
400 "end_date must be after start_date" Invalid date range
400 "Report period cannot exceed 5 years" Date range too long