Metric Export API

The Metric Export API delivers any metric of your plants as a time series, as CSV or JSON, with one GET request. It reads the same metric collection as the reports, including the metrics your organization defined itself.

Every link the Data Export page shows is a call of this API, so the easiest way to a working request is to build it there and copy it.

The export links of the previous export keep working unchanged. They are described in the Legacy Export API; how to move from one to the other is in the migration guide.

Routes

All paths follow https://service.mirox.io/api.

Authentication

Send an API token of the group Metric Export in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

The token reads every export route on this page and the legacy routes. It cannot create, change or delete anything. In a browser where you are logged in to Mirox, the links work without a token.

You only receive data of the plants whose measurements you may read. The metrics of your organization are exported by every organization role except External. See Who can export what.

Exporting a Time Series

GET /v1/export/series

Grid feed-in of one plant over the previous month, per day:

curl --compressed "https://service.mirox.io/api/v1/export/series?park=ABC123DEF456&metrics=plant.grid_feedin&window=previous_month&step=day" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o feedin.csv

Date;Grid feed-in (kWh)
2026-08-01;5321,4
2026-08-02;4980,2
...

Parameters

lane_limit and lane_page outside their bounds are set to the nearest bound. A parameter the route does not know is ignored.

Metrics and Values

A metric id has the form <prefix>.<name>, for example plant.grid_feedin, inverter.ac_power or sensor.irradiance. A metric of your organization is organization.<id of the metric>. The catalog lists all of them.

Each metric has a quantity, which decides the value modes it offers:

A suffix sets the mode of one metric and wins over values:

metrics=plant.grid_feedin:cumulative,plant.grid_power

A mode that does not apply to a metric is never an error. The metric is exported as native, and the note value_mode_ignored says so. delta is never applied to a power.

The same metric in two modes gives two columns. The same metric in the same mode twice gives one.

Time Range

Give the range in one of three ways. Two ways in one request answer 400 window_conflict.

Free range. start and end are a date (2026-07-01) or a date with time (2026-07-01T06:00, 2026-07-01T06:00:00Z, 2026-07-01T06:00:00+02:00). A value without a time zone is read in the time zone of the rows. An end that is a date includes that day; an end with a time is the moment the range ends. Without end, the range ends now. end alone, without start, is refused.

Calendar. year from 2020 to 2100, quarter 1 to 4, month 1 to 12, week 1 to 53 (ISO week), day 1 to 31. day needs month. Without year, the current year is meant. day wins over week, week over month, month over quarter.

Presets. today, yesterday, last_7_days, last_30_days, this_week, previous_week, this_month, previous_month, this_quarter, previous_quarter, this_year, previous_year. The this_ presets run up to now; last_7_days and last_30_days roll up to now at steps below a day (the same clock time 7 or 30 days back); at day and coarser they are the last 7 or 30 local days including today. At day and coarser every window is widened to whole days (weeks, months …) in the plant's time zone, and the response echoes the effective window.

A range starts in 2020 at the earliest and spans at most 1827 days (five years). A range that reaches into the future ends now, with the note end_clamped.

Steps

step=auto chooses a step that every requested metric serves and that fits the limits: 15min for up to two days, 1h for up to 62 days, day for up to three years, month beyond. If that step does not fit, the next coarser one is tried, then the finer ones. The note step_auto and the header X-Mirox-Step name the step that was chosen.

Each metric offers its own steps. The catalog lists them as export_steps:

Power is offered at 15 minutes or finer only. A daily or monthly power is an average that hides what happened; the energy metric gives the figure that is meant.

A step is never changed silently. With mismatch=refuse, the default, a step that one of the metrics does not serve answers 400 step_not_served with the steps of every metric, and with step=auto, metrics that share no step answer 400 no_common_step. With mismatch=sparse, such a request is delivered instead — see Metrics with different steps.

Steps of a day or longer cover whole intervals. A range that starts or ends inside one is widened outward, with the note window_aligned. Weeks start on Monday.

Metrics With Different Steps

mismatch=sparse delivers a request whose metrics do not all serve the step, as long as each of them serves some step. The grid of the file is the requested step; with step=auto it is the step that most metrics serve as is, chosen by the range and the limits as usual. Column positions and the shape of the CSV and JSON answer do not change.

Two cases are refused in both modes, with 400 step_not_served: a figure per month, quarter or year on a week file, because its first day is hardly ever a Monday; and a monthly figure such as the Marktwert on a quarter or year file, because a sum or a mean of months is not that figure. On a month file it is read as is, on a finer file it is sparse.

The estimate lists the same notes, counts the reads at each metric's own step, and marks a step in per_step as within budget even when not every metric serves it. The Data Export page always asks with mismatch=sparse; a template carries its own mismatch in its spec.

Time Grid

With tz=local, rows follow the local time of the plant, including daylight saving time: a day is a local day of 23, 24 or 25 hours, a month is a local month. With tz=utc, rows follow the UTC calendar.

• At steps shorter than a day in local time, the column UTC offset follows the time column (+02:00). On the day the clocks go back, one hour appears twice; the offset tells the two apart. offset_column=false leaves the column out.
• Plants in different time zones share one time column. Such a request is answered on the UTC calendar, with the note merged_on_utc, whether the plants are combined or split.
• With tz=utc and a step of a day or longer, a metric that exists per local day only has no UTC value. Its column stays empty, with the note utc_calendar_unsupported.

The header X-Mirox-Grid names the calendar that was used: local:Europe/Berlin or utc.

Several Plants

With multi_park_agg=merge, every metric is one column for all plants, combined by the rule of the metric. The catalog lists the rule as merge:

A metric that cannot be combined is exported per plant, with the note merge_not_meaningful. This also holds for a ratio at a step at which its two halves are not available, and for prices of plants in different market zones.

With multi_park_agg=split, every metric is one column per plant. With a single plant, both give the same file.

Component metrics are always per plant (note components_split_by_park).

Components

A metric of a component level gives one column per component. The levels are inverter, gak (combiner box), string, turbine, sensor, meter, battery_box (container), battery_storage (rack), battery_module, battery_cell and battery_pcs (power converter).

Without components, the export carries all visible components of the plants, lane_limit per metric and page. If there are more, the note lanes_truncated names the total; request the next page with lane_page.

components restricts the export to the components you name. A reference has the form <level>:<id>, for example inverter:1043. A sensor or meter that Mirox measures but that has no entry in the plant's components has a reference of the form sensor:h3f9c2a71b04e6d5. The components route lists the references of a plant. A reference that belongs to none of the selected plants answers 400 unknown_lane.

metrics=inverter.ac_power&components=inverter:1043,inverter:1044

Raw MetricsQL Queries

expr adds a raw query in MetricsQL, the query language of the platform's time-series store, to an export — for a series the collection has no metric for. The parameter can be repeated up to five times; each expression may have up to 4 000 characters. A request may carry expr alone, or metrics and expr together; the metric columns come first.

expr=sum by (inverter_id) (powerplant_inverter_power_ac)&park=ABC123DEF456&window=yesterday&step=15min

An expression is evaluated per plant, as a dashboard evaluates it: on the plant's own data, at the requested step, as raw samples — every step is allowed, values and the folding rules of the metrics do not apply. Mirox adds the plant to every selector of the expression; an expression that names a park, organization or plant label itself is refused with 400 expr_forbidden_label.

When an expression answers several series on any of its plants, every plant's columns of that expression carry the series labels, so a file has one naming per expression. A heading longer than 1 000 characters is cut with … inside the expression, never in the series text. In the JSON answer, columns[].key is the header=id text and columns[].metric is the expression's id, expr.e1, expr.e2, …, which the notes and refusals use. A plant on which the expression answers nothing keeps one empty column, with the note expr_no_series; with several plants, every plant gets its own columns, with the note expr_split_by_park.

An expression may answer at most 500 series on one plant (400 expr_too_many_series); aggregate it, with sum by (…) for example. The series count against the same 400 columns and 1 800 000 values as every export: the first read of each expression on each plant is a short probe, the widths are summed over the whole request, and a request that outgrows the limits is refused with 400 over_budget and params.series before any full read of any expression. An expression that does not parse, is empty, is too long, or that the store refuses answers 400 expr_invalid with the reason.

The estimate counts an expression as one column per plant, because its series are only known once it is read. Expressions are not stored in templates.

CSV Answer

The answer is UTF-8, with the file name series_export_<first day>_<last day>_<step>.csv. An answer larger than about 1 MB is compressed when the request carries Accept-Encoding: gzip (curl: --compressed).

The columns are, in this order: the time, the UTC offset where it applies, then the metrics in the order of metrics.

The time column is formatted per step unless datetime_format is given:

Every row is stamped with the start of its interval. A missing value is an empty cell, so "no data" and "zero" can be told apart; empty=zero writes 0 instead.

Four headers of the answer repeat what was resolved:

JSON Answer

format=json answers the same table as structured data:

Notes

A note tells you what Mirox did on its own. It never fails an export. Notes are part of the JSON answer and of the header X-Mirox-Notes. The header holds up to 1 KB of notes, written as code:key=value,key=value and separated by ;. If not all of them fit, the header ends with notes_omitted:count=<n>; the JSON answer holds all of them.

An empty column is always kept. A metric that does not apply to one of the plants, or a money metric without the accounting permission, leaves its column in place, so the positions of the other columns never move.

Estimating Before Exporting

GET /v1/export/series/estimate

The route takes the parameters of the export, without the file format, and answers what the export would be — without reading data and without counting against the hourly allowance.

A refusal never fails the estimate: it answers 200 and lists the refusal. The estimate counts, it renders nothing: the row labels and headings are the export's. A raw query counts as one column per plant, and with mismatch=sparse the notes name the folded and sparse columns.

The Metric Catalog

GET /v1/export/series/catalog

Each metric carries, next to its id, name, description, unit and level:

For up to 10 plants, each plant is checked for the equipment a metric needs. Above that, plants are judged by their type only; what a single plant lacks shows at export time as a note metric_unavailable.

Glossary. format=csv answers the whole filtered list as a file, metric_catalog_<language>.csv, with the columns id, level, name, unit, description, quantity, value modes, steps, measuring interval, combination over plants, note and previous ids. page and limit do not apply.

curl "https://service.mirox.io/api/v1/export/series/catalog?format=csv&language=en" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o metric_catalog_en.csv

Available Metrics

The collection is ordered by level. The prefix of an id tells where a metric belongs.

The complete list with names, units and descriptions in your language is the catalog, the glossary file, or Explanations on the Metrics tab. The weather forecast values of the previous export are not part of the collection; see the migration guide.

Components of a Plant

GET /v1/export/series/lanes

Each entry has the reference ref for the parameter components, the name, the level, the parent (parent_ref, parent_name — the inverter of a string, for example), attributes (role of a meter, position of an irradiance sensor, vendor), hidden, and source: db for an entry of the plant's components, store for a series that is measured but has no such entry.

A plant that does not exist and a plant you cannot read both answer 404 park_not_found.

Template System

A template is a saved list of metrics with defaults for step, time range, values, time zone, combination of plants, component page size and column headers. What templates are for, and how to manage them in the app, is in the Metric Export guide.

Exporting a Template

GET /v1/export/series/template/{template_uid}

The route takes the parameters of the export except metrics, components and values, which the template fixes. Every parameter you leave out takes the template's default; every parameter you give wins over it.

curl --compressed "https://service.mirox.io/api/v1/export/series/template/CAFE1000CAFE?park=ABC123DEF456&window=previous_month&header=id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o standard.csv

• A template of another organization answers 404 template_not_found.
• A legacy template answers 400 template_is_legacy; params.legacy_url is the link that exports it.
• A column whose metric is no longer available is exported empty under its header, with the note metric_unavailable. The same holds for a metric of your organization when you export as External (reason not_permitted).

System Templates

The first five succeed CAFE0000CAFE, CAFE0001CAFE, CAFE0002CAFE, CAFE0003CAFE and ABCD12340001, which keep working on the legacy route. Their columns are listed in the migration guide. They offer the steps day, week, month, quarter and year; the first four also offer 15min and 1h.

Managing Templates

Templates are listed, read, created, changed and deleted under /v1/export/template. Reading works with a Metric Export token. Writing needs the organization role Admin, Moderator, Asset Manager (Technical) or Asset Manager (Commercial) and a login or a Full Access token.

The spec of a template:

label is the header text of the column with header=name. A metric may appear once, and a template holds no raw queries. When a template is saved, every metric must be exportable, and the metrics must share a step — under mismatch=sparse, each must serve some step; otherwise the answer is 422 spec_invalid and params.problems names the metric and the reason. A template runs with its own mismatch (the app shows it as Metrics of another step: Strict or Lenient); the parameter on the export link wins over it.

Converting a Legacy Template

POST /v1/export/template/{template_uid}/convert

The answer lists mapped (legacy_id, metric, values, exactness: exact or approximate) and unmapped (legacy_id, reason: formula, no_equivalent, report_value or instant, and up to three suggestions), and, unless it was a dry run, the new template. A dry run answers 200, a conversion 201.

The new template exports days over the previous month. The legacy template is never changed. Two legacy columns that read the same meter become one column. 422 nothing_to_convert means that no column has a counterpart, or that the template is not a legacy template.

Limits

An export is answered within one request, so its size is bounded. Every limit is checked before data is read; a request that is too large is refused at once and tells you what would fit.

Splitting a Large Export

400 over_budget names in params what was needed and what is allowed, and in hint the way out: step, the next coarser step that fits, and max_days, the longest range that fits at the requested step. Ask the estimate first if you build requests in a script; its per_step lists the size for every step.

If neither a coarser step nor a shorter range is what you want, split the export:

Some metrics are worked out from several sources for every day, above all plant.production_reported (Production, resolved). They need many more reads of the measurement store than a meter reading, at every step. A request or a template that carries such a metric reaches about nine plant-months at present: one plant over nine months, or nine plants over one month. A step of a week or longer widens the range to whole intervals, and the widened range counts. Split such exports by time or by plant, or export the metric in a request of its own.

429 busy and 429 rate_limited carry the header Retry-After with the seconds to wait.

Errors

An error of the routes on this page has this form:

{
  "detail": {
    "code": "step_not_served",
    "message": "The step is not served by every requested metric.",
    "params": {"step": "1h", "metrics": {"plant.grid_power": ["1min", "5min", "15min"]}},
    "hint": {"offered_common": ["1min", "5min", "15min"]}
  }
}

code is stable and meant for programs. message is an English text for people. params says what was wrong, hint what would work.

401 means that the token is missing, expired or revoked.

Ids of the Previous Export

The parameter metrics also accepts the ids of the previous export, such as energy_grid_daily or raw_grid_power. An id with a counterpart is translated to its metric, in the value mode that comes closest to the previous number, and the note legacy_id_mapped says which metric answered and whether the number is the same (exact) or the same quantity read in a better way (approximate).

An id without a counterpart answers 400 legacy_metric_id. hint.reason says why, hint.closest names the nearest metric where there is one, hint.pending names the metric that is planned to carry it, and legacy_url is the link of the previous export that still delivers the id. With more plants than a link can name, legacy_url names the first plant and params.legacy_url_scope is first. A component id of a battery level has no link of the previous export; hint.legacy_route is none then. The migration guide lists every id.

Excel and Scripts

• Metric Export for Excel — recipes, and the Power Query connection with the Authorization header
• External Report Generator — a complete Python example

Related Features

• Metric Export — the Data Export page
• Migrating to the Metric Export — old ids, new metrics and what changes
• Legacy Export API — the previous export links
• Metrics — define metrics of your own and export them
• API Tokens — create the Metric Export token
• API Overview — the interactive reference of all routes