Export Metric API
Extract processed, report-ready time-series data from your plants in a single call — across one park, many parks, or whole portfolios. The export system is built around templates that define which metrics to export and in what order, so the same numbers you see in a generated report are the numbers you pull through the API.
The canonical CSV download is GET /v1/export/metrics/template/{template_uid}. A JSON variant and a separate raw time-series export cover in-app charts and high-resolution power curves; all three are described below.
Open in Mirox
Build and run an export interactively at Data Export ▸ Builder, or manage your templates at Data Export ▸ Templates. The same templates and metrics described here power both the in-app builder and the API.
Understanding Metric Types
The Mirox platform works with two distinct types of metrics that serve different purposes:
Raw Metric Collection
Raw metrics are the foundation of the platform's data infrastructure. These metrics are:
- Collected directly from hardware: Scraped from inverters, sensors, and data loggers
- Stored as-is in the time series database: Preserves original granularity and structure
- Optimized for real-time monitoring: Enables live dashboards and instant queries
- Multi-dimensional: Uses labels to split data by component, location, or type
- Cumulative counters: Often stores total energy values that increase over time
- High frequency: Can be collected every few seconds or minutes
Raw metrics are essential for system operation but are not optimized for user-friendly data export. They require transformation, aggregation, and interpretation to become meaningful business metrics.
For detailed information about raw metric collection, see Metric Collection Architecture.
Export Metrics
Export metrics are processed, user-friendly metrics designed specifically for data export and reporting:
- Pre-aggregated: Calculated on a daily basis by default
- Cleaned and validated: Data quality checks applied
- User-friendly naming: Clear, descriptive identifiers
- Consistent units: Standardized across all metrics
- Ready for analysis: No additional transformation required
- Business-oriented: Focused on KPIs and reporting needs
Export metrics are identified by metric_id strings (e.g., energy_grid_daily, availability_technical) and form the foundation of the export system.
Tips
When using the Export Metric API, you're always working with export metrics. The raw metric collection is automatically transformed into these export-ready formats by the platform.
Key Features
- Template-Based Exports: Define reusable metric configurations
- Multi-Park Support: Export aggregated data from multiple parks or portfolios in one request
- Multiple Export Formats: CSV with configurable separators for international compatibility, plus a JSON variant for in-app charts
- Flexible Time Ranges: Export by year, quarter, month, week, or a single day
- Aggregation Options: Daily, weekly, monthly, quarterly, or yearly aggregation
- International Support: Customizable date formats and decimal separators
- Custom Metrics: Define your own metrics using MiroxQL formulas
Choosing the Right Export
The platform offers three distinct export paths. Pick the one that matches your goal:
| Export | Endpoint | Output | Best For |
|---|---|---|---|
| Template CSV | GET /v1/export/metrics/template/{template_uid} | CSV download | Reports, spreadsheets, billing — pre-defined, aggregated, formula-aware columns across one or many parks |
| Template JSON | POST /v1/export/metrics/query | JSON | Charts and previews inside your own application — same aggregation engine, returns rows of dated values |
| Raw Time Series | POST /v1/export/raw/query | JSON | High-resolution power curves at your chosen step (5m, 15m, 1h, 1d) — arbitrary raw queries, not aggregated |
The Template CSV route is the canonical metrics export and the focus of this guide. For programmatic, formula-driven access to your data, see MiroxQL Query Language — the supported way to query and shape raw figures into custom metrics.
Multi-Park in One Call
The Template CSV and JSON exports accept comma-separated park and portfolio query parameters, so you can pull a portfolio-wide aggregation in a single request. When both are supplied, the parks of each portfolio are unioned with the explicitly listed parks.
Template System
What are Export Templates?
Export templates are predefined or custom configurations that specify:
- Which metrics to include in the export
- The order of metrics in the output
- Metadata about each metric (name, unit, category, description)
Templates enable consistent, repeatable exports and can be shared across an organization. To create, edit, or share templates without writing any code, open Data Export ▸ Templates in Mirox.
Predefined System Template
The system provides a comprehensive default template that includes all essential metrics for solar park monitoring and reporting.
Report Technical v1 Template (UID: ABCD12340001):
This comprehensive template is used for both PDF report generation and CSV exports. It includes:
Time Series Metrics:
- Energy Production (kWh) -
energy_grid_daily - Energy Radiation Total (kWh) -
energy_radiation_daily - GTI Sensor (kWh/m²) -
gti_sensor_daily - GTI Weather (kWh/m²) -
gti_weather_daily - Sunhours (h) -
sunhours_daily - Availability Inverter (%) -
availability_inverter - Availability Energy (%) -
availability_energy - Availability Data (%) -
availability_data - Availability Sensor (%) -
availability_sensor - Energy Shutdown by Grid (kWh) -
energy_shutdown_grid_daily - Energy Shutdown by External (kWh) -
energy_shutdown_external_daily
Report Configuration Metrics:
- Energy Report (kWh) -
energy_report - GTI Report Incident (kWh/m²) -
gti_report - GTI Report Effective (kWh/m²) -
gti_report_eff - PR Report Target (%) -
pr_report
Calculated Metrics (using MiroxQL):
- Irradiance Analysis (actual, weather usage, sensor-weather difference)
- Production Targets (weather-based, sensor-based, actual, corrected)
- Performance Ratios (weather, sensor, actual, corrected)
- Specific Yield (Wh/W)
- Loss Analysis (non-compensable losses)
Consistent Data Across Reports and Exports
This template is used for both PDF Report Generation and API exports, ensuring that internally generated reports and user-exported data contain exactly the same metrics and calculations. This consistency is a core feature of the platform, enabling reliable data validation and comparison.
For information about custom calculated metrics, see MiroxQL Query Language.
Available Export Metrics
All metrics are calculated on a daily basis and can be aggregated to weekly, monthly, quarterly, or yearly intervals. Each metric includes a simplified formula showing how the value is derived from raw metrics.
Energy Production Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
energy_grid_daily | Energy Production | kWh | Daily energy fed into the grid | sum(delta(grid_energy_total)) per component |
energy_ac_daily | AC Production | kWh | Daily AC energy production | sum(delta(ac_energy_total)) per component |
energy_inverter_daily | Inverter Production | kWh | Daily energy production from inverters | sum(delta(inverter_ac_energy_total)) per inverter |
energy_radiation_daily | Energy Radiation Total | kWh | Daily total energy radiation | sum(delta(radiation_energy_total)) per component |
Shutdown/Loss Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
energy_shutdown_grid_daily | Energy Shutdown by Grid | kWh | Daily energy loss due to grid constraints | sum(delta(energy_loss_total)) where type='grid', per component |
energy_shutdown_external_daily | Energy Shutdown by External | kWh | Daily energy loss due to external control | sum(delta(energy_loss_total)) where type='external', per component |
Irradiance Metrics
Global Tilted Irradiance (GTI) metrics are comparable and measure solar radiation on the tilted plane of the solar modules.
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
gti_sensor_daily | GTI Sensor | kWh/m² | Daily global tilted irradiation from sensors | avg(delta(irradiation_total)) where position='module-level' or fallback |
gti_weather_daily | GTI Weather | kWh/m² | Daily global tilted irradiation from weather forecast | sum(weather_gti) / 4, sampling: 15min intervals |
gti_report | GTI Report | kWh/m² | GTI target from park configuration | value from park configuration |
Weather Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
solar_radiation_daily | Solar Radiation | Wh | Average daily solar radiation | avg(solar_radiation) over 24h |
sunhours_daily | Sunhours | h | Daily hours of sunshine | count(weather_gti > 0) / 4, sampling: 15min |
Environmental Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
temperature_ambient_avg | Ambient Temperature | °C | Average daily ambient temperature | avg(ambient_temperature) over 24h |
temperature_module_avg | Module Temperature | °C | Average daily module temperature | avg(module_temperature) over 24h |
wind_speed_avg | Wind Speed | m/s | Average daily wind speed | avg(wind_speed) over 24h |
humidity_avg | Humidity | % | Average daily humidity | avg(humidity) over 24h |
Availability Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
availability_inverter | Availability Inverter | % | Inverter availability based on power output and GTI conditions | avg(1 - count(inverter_power ≤ 0 AND weather_gti > 100)), sampling: 15min |
availability_technical | Availability Technical | % | Technical availability of the system | avg(sum(scraper_health == 1) / count(scraper_health)) per source, sampling: 15min |
availability_data | Availability Data | % | Data availability from the plant | 1 - avg(count(grid_energy_total)) where absent, sampling: 15min |
availability_sensor | Availability Sensor | % | Sensor availability | 1 - avg(count(solar_radiation)) where absent, sampling: 15min |
availability_energy | Availability Energy | % | Energy-based availability approximation | 1 - (sum(energy_loss_total) / (sum(grid_energy_total) + sum(energy_loss_total))) |
Technical Availability Changes Over Time
The availability_technical metric scope expands as new platform features are added. This can cause the value to decrease when new features are deployed, even if existing systems function normally. For stable historical comparisons, use specific metrics like availability_inverter, availability_data, or availability_sensor.
Battery Metrics
Battery aggregations operate at the box level of the BESS hierarchy — the canonical "whole BESS" view defined by the BATTERY enum. See the Metric Collection page for the full component hierarchy (environment / box / storage / module / cell).
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
battery_energy_in_daily | Battery Energy Charged | kWh | Daily DC energy charged into the battery | sum(delta(battery_box_energy_dc_in_total)) per box |
battery_energy_out_daily | Battery Energy Discharged | kWh | Daily DC energy discharged from the battery | sum(delta(battery_box_energy_dc_out_total)) per box |
battery_soc_avg | Battery State of Charge | % | Average daily box-level state of charge | avg(battery_box_soc) over 24h |
battery_soh_avg | Battery State of Health | % | Average daily box-level state of health | avg(battery_box_soh) over 24h |
battery_energy_charged_avg | Battery Stored Energy | kWh | Average daily energy currently stored | avg(sum(battery_box_energy_charged)) over 24h |
temperature_battery_avg | Battery Temperature | °C | Average daily box-level battery temperature | avg(battery_box_temperature) over 24h |
Report Metrics
| Metric ID | Name | Unit | Description | Formula |
|---|---|---|---|---|
energy_report | Energy Report | kWh | Energy target from park configuration | value from park configuration |
Time Range and Aggregation
Selecting the Time Range
Choose what slice of history to export with these selectors:
- Year: a full calendar year
- Quarter: a quarter of a given year
- Month: a single calendar month
- Week: a single calendar week
- Day: a single day (requires a month to be set)
Aggregation Resolution
Within the selected range, the daily values are rolled up to your chosen resolution. Energy and hour-based metrics are summed; all other metrics are averaged.
Daily Aggregation
- Raw daily values from the platform's time series store
- Highest granularity available
- Best for detailed analysis and troubleshooting
- File size: Large
Weekly Aggregation
- Data aggregated by ISO week (Monday to Sunday)
- Includes week number and calendar week columns
- A
full_weekoption extends partial first and last weeks to complete ISO weeks - Suitable for trend analysis
- File size: Medium
Monthly Aggregation
- Data aggregated by calendar month
- Includes "Days in Month" column for normalization
- Best for reporting and long-term trends
- File size: Small
Quarterly and Yearly Aggregation
- Data rolled up to calendar quarters or full years
- Best for executive summaries and year-over-year comparison
- File size: Smallest
International Format Support
CSV Separators
The API supports multiple CSV separators for regional compatibility:
- Comma (
,): Standard in US/UK - Semicolon (
;): Standard in Germany and many European countries - Tab (
\t): Universal, good for Excel import - Pipe (
|): Alternative for special cases
Decimal Separators
- Dot (
.): Standard in US/UK (e.g., 1234.56) - Comma (
,): Standard in Germany and many European countries (e.g., 1234,56)
Caution
The CSV separator and decimal separator must be different to avoid parsing issues.
Date Formats
Custom datetime formats can be specified using Python strftime syntax:
Common formats:
%Y-%m-%d: ISO format (2025-03-15)%d/%m/%Y: European format (15/03/2025)%m/%d/%Y: US format (03/15/2025)%d.%m.%Y: German format (15.03.2025)%Y-%m: Month only (2025-03)%Y-W%W: ISO week format (2025-W11)
CSV Output Format
The exported CSV files include headers with metric names and units. The structure varies based on the aggregation interval:
Monthly Export
Includes a "Days in Month" column for normalization.
Weekly Export
Includes both "Date" (ISO week format) and "Calendar Week" (week number) columns.
Daily Export
One row per day with date in specified format.
Use Cases
Custom Reporting
Create specialized export templates for:
- Monthly performance reports
- Quarterly stakeholder updates
- Annual compliance reporting
- Custom KPI tracking
Third-Party Integration
Export data for integration with:
- Energy management systems
- Business intelligence platforms
- Carbon accounting software
- Portfolio management tools
Data Analysis
Feed the exported figures into your own analytics:
- Performance benchmarking
- Seasonal trend analysis
- Feeding business intelligence and reporting pipelines
Authentication and Permissions
All export endpoints require an authenticated session. You can drive them from a browser session or with an API token carrying the reporting permission group.
What you need:
- Template Management: rights to read, create, modify, or delete export templates within your organization. System templates are read-only for everyone.
- Metrics Export: read access to export reports.
- Park Access: you only ever receive data for the parks and portfolios you are permitted to see. Requested parks you cannot access are silently filtered out — and if none remain accessible, the request is rejected.
Best Practices
- Choose Appropriate Templates: Use predefined templates when possible, create custom ones for specific needs
- Select Correct Aggregation: Use monthly for reports, daily for detailed analysis
- Set Proper Separators: Match your local Excel/CSV settings
- Multi-Park Exports: Leverage multi-park capabilities for portfolio-level analysis
- Template Reusability: Create organization-wide templates for consistent reporting
- Use MiroxQL: Define custom calculated metrics for advanced analysis
Practical Example
For a complete implementation example of custom report generation using the Export Metric API, see the Report Generator Example. This example demonstrates how to fetch data from the API, process it, and generate custom reports with visualizations.
Error Handling
Common error responses:
- 404 Not Found: Template, park, or portfolio doesn't exist
- 403 Forbidden: Insufficient permissions or no accessible parks
- 422 Validation Error: Invalid parameters (e.g., invalid metric IDs)
- 400 Bad Request: Invalid parameter combinations (e.g., same CSV and decimal separator)
- 409 Conflict: Template name already exists in organization
Related Features
- MiroxQL Query Language — define custom calculated metrics for your templates
- External Report Generation — automate template CSV exports into your own report workflow
- Report Generator Example — a runnable Python example end to end
- Reports — automated PDF report generation using the same templates
- API Tokens Guide — set up an API token to authenticate exports