API de Metric Export

La API de Metric Export entrega cualquier métrica de tus plantas como serie temporal, en CSV o JSON, con una sola solicitud GET. Lee la misma colección de métricas que los informes, incluidas las métricas que tu organización ha definido.

Cada enlace que muestra la página Exportación de datos es una llamada a esta API, así que la forma más fácil de llegar a una solicitud que funcione es construirla allí y copiarla.

Los enlaces de exportación de la exportación anterior siguen funcionando sin cambios. Se describen en la API de exportación heredada; cómo pasar de una a otra está en la guía de migración.

Rutas

Todas las rutas siguen a https://service.mirox.io/api.

Autenticación

Envía un token de API del grupo Metric Export en el encabezado Authorization:

Authorization: Bearer YOUR_API_TOKEN

El token lee todas las rutas de exportación de esta página y las rutas heredadas. No puede crear, modificar ni eliminar nada. En un navegador en el que has iniciado sesión en Mirox, los enlaces funcionan sin token.

Solo recibes datos de las plantas cuyas mediciones puedes leer. Las métricas de tu organización las exportan todos los roles de organización excepto Externo. Consulta Quién puede exportar qué.

Exportar una serie temporal

GET /v1/export/series

Inyección a red de una planta durante el mes anterior, por día:

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
...

Parámetros

lane_limit y lane_page fuera de sus límites se ajustan al límite más cercano. Un parámetro que la ruta no conoce se ignora.

Métricas y valores

Un id de métrica tiene la forma <prefijo>.<nombre>, por ejemplo plant.grid_feedin, inverter.ac_power o sensor.irradiance. Una métrica de tu organización es organization.<id de la métrica>. El catálogo las enumera todas.

Cada métrica tiene una magnitud, que decide los modos de valores que ofrece:

Un sufijo fija el modo de una métrica y prevalece sobre values:

metrics=plant.grid_feedin:cumulative,plant.grid_power

Un modo que no se aplica a una métrica nunca es un error. La métrica se exporta como native, y la nota value_mode_ignored lo indica. delta nunca se aplica a una potencia.

La misma métrica en dos modos da dos columnas. La misma métrica dos veces en el mismo modo da una.

Periodo

Indica el periodo de una de tres formas. Dos formas en una misma solicitud responden 400 window_conflict.

Periodo libre. start y end son una fecha (2026-07-01) o una fecha con hora (2026-07-01T06:00, 2026-07-01T06:00:00Z, 2026-07-01T06:00:00+02:00). Un valor sin zona horaria se lee en la zona horaria de las filas. Un end que es una fecha incluye ese día; un end con hora es el momento en que termina el periodo. Sin end, el periodo termina ahora. end solo, sin start, se rechaza.

Calendario. year de 2020 a 2100, quarter de 1 a 4, month de 1 a 12, week de 1 a 53 (semana ISO), day de 1 a 31. day necesita month. Sin year, se entiende el año en curso. day prevalece sobre week, week sobre month, month sobre quarter.

Periodos predefinidos. today, yesterday, last_7_days, last_30_days, this_week, previous_week, this_month, previous_month, this_quarter, previous_quarter, this_year, previous_year. Los periodos this_ llegan hasta ahora; last_7_days y last_30_days son móviles hasta ahora con pasos inferiores a un día (la misma hora 7 o 30 días atrás); desde day son los últimos 7 o 30 días locales incluido hoy. Desde day cada ventana se amplía a días completos (semanas, meses …) en la zona horaria de la planta, y la respuesta devuelve la ventana efectiva.

Un periodo empieza como muy pronto en 2020 y abarca como máximo 1827 días (cinco años). Un periodo que llega al futuro termina ahora, con la nota end_clamped.

Pasos

step=auto elige un paso que ofrezcan todas las métricas solicitadas y que encaje con los límites: 15min hasta dos días, 1h hasta 62 días, day hasta tres años, month a partir de ahí. Si ese paso no encaja, se prueba el siguiente más grueso y después los más finos. La nota step_auto y el encabezado X-Mirox-Step nombran el paso elegido.

Cada métrica ofrece sus propios pasos. El catálogo los enumera como export_steps:

La potencia se ofrece solo con 15 minutos o más fino. Una potencia diaria o mensual es un promedio que oculta lo que ocurrió; la métrica de energía da la cifra que se busca.

Un paso nunca se cambia en silencio. Con mismatch=refuse, el valor predeterminado, un paso que una de las métricas no ofrece responde 400 step_not_served con los pasos de cada métrica, y con step=auto las métricas que no comparten ningún paso responden 400 no_common_step. Con mismatch=sparse, esa solicitud se entrega igualmente: consulta Métricas con distintos pasos.

Los pasos de un día o más cubren intervalos completos. Un periodo que empieza o termina dentro de uno de ellos se amplía hacia fuera, con la nota window_aligned. Las semanas empiezan el lunes.

Métricas con distintos pasos

mismatch=sparse entrega una solicitud cuyas métricas no ofrecen todas el paso, siempre que cada una ofrezca algún paso. La cuadrícula del archivo es el paso solicitado; con step=auto es el paso que más métricas ofrecen tal cual, elegido por el periodo y los límites como de costumbre. Las posiciones de las columnas y la forma de la respuesta CSV y JSON no cambian.

Dos casos se rechazan en ambos modos con 400 step_not_served: una cifra por mes, trimestre o año en un archivo por week, porque su primer día casi nunca es lunes; y una cifra mensual como el Marktwert en un archivo por quarter o year, porque una suma o un promedio de meses no es esa cifra. En un archivo por month se lee tal cual; en uno más fino queda dispersa.

La estimación enumera las mismas notas, cuenta las lecturas con el paso propio de cada métrica y marca un paso en per_step como dentro del límite aunque no todas las métricas lo ofrezcan. La página Exportación de datos pregunta siempre con mismatch=sparse; una plantilla lleva su propio mismatch en su spec.

Rejilla de tiempo

Con tz=local, las filas siguen la hora local de la planta, incluido el horario de verano: un día es un día local de 23, 24 o 25 horas, un mes es un mes local. Con tz=utc, las filas siguen el calendario UTC.

• Con pasos más cortos que un día en hora local, la columna Desfase UTC sigue a la columna de tiempo (+02:00). El día en que los relojes se atrasan, una hora aparece dos veces; el desfase distingue una de otra. offset_column=false omite la columna.
• Las plantas en zonas horarias distintas comparten una sola columna de tiempo. Una solicitud así se responde en el calendario UTC, con la nota merged_on_utc, tanto si las plantas se combinan como si se separan.
• Con tz=utc y un paso de un día o más, una métrica que solo existe por día local no tiene valor UTC. Su columna queda vacía, con la nota utc_calendar_unsupported.

El encabezado X-Mirox-Grid nombra el calendario que se usó: local:Europe/Berlin o utc.

Varias plantas

Con multi_park_agg=merge, cada métrica es una columna para todas las plantas, combinada según la regla de la métrica. El catálogo enumera la regla como merge:

Una métrica que no se puede combinar se exporta por planta, con la nota merge_not_meaningful. Esto vale también para un ratio con un paso en el que sus dos mitades no están disponibles, y para los precios de plantas en zonas de mercado distintas.

Con multi_park_agg=split, cada métrica es una columna por planta. Con una única planta, ambas dan el mismo archivo.

Las métricas de componentes son siempre por planta (nota components_split_by_park).

Componentes

Una métrica de un nivel de componente da una columna por componente. Los niveles son inverter, gak (caja de conexión), string, turbine, sensor, meter, battery_box (contenedor), battery_storage (rack), battery_module, battery_cell y battery_pcs (convertidor).

Sin components, la exportación lleva todos los componentes visibles de las plantas, lane_limit por métrica y página. Si hay más, la nota lanes_truncated nombra el total; solicita la página siguiente con lane_page.

components restringe la exportación a los componentes que nombras. Una referencia tiene la forma <nivel>:<id>, por ejemplo inverter:1043. Un sensor o contador que Mirox mide pero que no tiene entrada en los componentes de la planta tiene una referencia de la forma sensor:h3f9c2a71b04e6d5. La ruta de componentes enumera las referencias de una planta. Una referencia que no pertenece a ninguna de las plantas seleccionadas responde 400 unknown_lane.

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

Consultas MetricsQL en bruto

expr añade a una exportación una consulta en bruto en MetricsQL, el lenguaje de consulta de la base de datos de series temporales de la plataforma, para una serie para la que la colección no tiene métrica. El parámetro puede repetirse hasta cinco veces; cada expresión puede tener hasta 4 000 caracteres. Una solicitud puede llevar solo expr, o metrics y expr juntos; las columnas de las métricas van primero.

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

Una expresión se evalúa por planta, como la evalúa un panel: sobre los datos de la propia planta, con el paso solicitado, como muestras brutas. Se admite cualquier paso, y values y las reglas de agregación de las métricas no se aplican. Mirox añade la planta a cada selector de la expresión; una expresión que nombra por sí misma una etiqueta park, organization o plant se rechaza con 400 expr_forbidden_label.

Cuando una expresión responde varias series en alguna de sus plantas, las columnas de esa expresión en todas las plantas llevan las etiquetas de serie, de modo que un archivo tiene una sola forma de nombrar cada expresión. Un encabezado de más de 1 000 caracteres se corta con … dentro de la expresión, nunca en el texto de la serie. En la respuesta JSON, columns[].key es el texto de header=id y columns[].metric es el id de la expresión, expr.e1, expr.e2, …, que usan las notas y los rechazos. Una planta en la que la expresión no responde nada conserva una columna vacía, con la nota expr_no_series; con varias plantas, cada planta recibe sus propias columnas, con la nota expr_split_by_park.

Una expresión puede responder como máximo 500 series en una planta (400 expr_too_many_series); agrégala, por ejemplo con sum by (…). Las series cuentan para las mismas 400 columnas y 1 800 000 valores que cualquier exportación: la primera lectura de cada expresión en cada planta es una breve sonda, las anchuras se suman en toda la solicitud y una solicitud que supera los límites se rechaza con 400 over_budget y params.series antes de leer por completo ninguna expresión. Una expresión que no se puede analizar, está vacía, es demasiado larga o que la base de datos rechaza responde 400 expr_invalid con el reason.

La estimación cuenta una expresión como una columna por planta, porque sus series solo se conocen al leerla. Las expresiones no se guardan en las plantillas.

Respuesta CSV

La respuesta es UTF-8, con el nombre de archivo series_export_<primer día>_<último día>_<paso>.csv. Una respuesta de más de 1 MB aproximadamente se comprime cuando la solicitud lleva Accept-Encoding: gzip (curl: --compressed).

Las columnas son, en este orden: el tiempo, el Desfase UTC cuando corresponde, y después las métricas en el orden de metrics.

La columna de tiempo se formatea según el paso, salvo que se indique datetime_format:

Cada fila lleva la marca del inicio de su intervalo. Un valor ausente es una celda vacía, de modo que «sin datos» y «cero» se pueden distinguir; empty=zero escribe 0 en su lugar.

Cuatro encabezados de la respuesta repiten lo que se resolvió:

Respuesta JSON

format=json responde la misma tabla como datos estructurados:

Notas

Una nota te dice qué ha hecho Mirox por su cuenta. Nunca hace fallar una exportación. Las notas forman parte de la respuesta JSON y del encabezado X-Mirox-Notes. El encabezado contiene hasta 1 KB de notas, escritas como code:key=value,key=value y separadas por ;. Si no caben todas, el encabezado termina con notes_omitted:count=<n>; la respuesta JSON las contiene todas.

Una columna vacía siempre se conserva. Una métrica que no se aplica a una de las plantas, o una métrica monetaria sin el permiso de contabilidad, deja su columna en su sitio, de modo que las posiciones de las demás columnas nunca se mueven.

Estimar antes de exportar

GET /v1/export/series/estimate

La ruta acepta los parámetros de la exportación, sin el formato de archivo, y responde lo que sería la exportación, sin leer datos y sin contar para el cupo por hora.

Un rechazo nunca hace fallar la estimación: responde 200 y enumera el rechazo. La estimación cuenta, no genera nada: las etiquetas de fila y los encabezados son los de la exportación. Una consulta en bruto cuenta como una columna por planta, y con mismatch=sparse las notas nombran las columnas agregadas y dispersas.

El catálogo de métricas

GET /v1/export/series/catalog

Cada métrica lleva, junto a su id, nombre, descripción, unidad y nivel:

Con hasta 10 plantas, se comprueba en cada planta el equipamiento que necesita una métrica. Por encima de esa cifra, las plantas se evalúan solo por su tipo; lo que le falta a una planta concreta se muestra en el momento de exportar como una nota metric_unavailable.

Glosario. format=csv responde toda la lista filtrada como archivo, metric_catalog_<idioma>.csv, con las columnas id, nivel, nombre, unidad, descripción, magnitud, modos de valores, pasos, intervalo de medición, combinación entre plantas, nota e ids anteriores. page y limit no se aplican.

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

Métricas disponibles

La colección está ordenada por nivel. El prefijo de un id indica a dónde pertenece una métrica.

La lista completa con nombres, unidades y descripciones en tu idioma es el catálogo, el archivo de glosario o Explicaciones en la pestaña Métricas. Los valores de previsión meteorológica de la exportación anterior no forman parte de la colección; consulta la guía de migración.

Componentes de una planta

GET /v1/export/series/lanes

Cada entrada tiene la referencia ref para el parámetro components, el name, el level, el elemento superior (parent_ref, parent_name — el inversor de un string, por ejemplo), attributes (role de un contador, position de un sensor de irradiancia, vendor), hidden, y source: db para una entrada de los componentes de la planta, store para una serie que se mide pero no tiene tal entrada.

Una planta que no existe y una planta que no puedes leer responden ambas 404 park_not_found.

Sistema de plantillas

Una plantilla es una lista guardada de métricas con valores predeterminados para el paso, el periodo, los valores, la zona horaria, la combinación de plantas, el tamaño de página de componentes y los encabezados de columna. Para qué sirven las plantillas, y cómo gestionarlas en la aplicación, está en la guía de Metric Export.

Exportar una plantilla

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

La ruta acepta los parámetros de la exportación salvo metrics, components y values, que fija la plantilla. Cada parámetro que omites toma el valor predeterminado de la plantilla; cada parámetro que indicas prevalece sobre él.

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

• Una plantilla de otra organización responde 404 template_not_found.
• Una plantilla heredada responde 400 template_is_legacy; params.legacy_url es el enlace que la exporta.
• Una columna cuya métrica ya no está disponible se exporta vacía bajo su encabezado, con la nota metric_unavailable. Lo mismo ocurre con una métrica de tu organización cuando exportas como Externo (reason not_permitted).

Plantillas del sistema

Las cinco primeras suceden a CAFE0000CAFE, CAFE0001CAFE, CAFE0002CAFE, CAFE0003CAFE y ABCD12340001, que siguen funcionando en la ruta heredada. Sus columnas se enumeran en la guía de migración. Ofrecen los pasos day, week, month, quarter y year; las cuatro primeras ofrecen además 15min y 1h.

Gestionar plantillas

Las plantillas se enumeran, leen, crean, modifican y eliminan bajo /v1/export/template. La lectura funciona con un token Metric Export. La escritura necesita el rol de organización Administrador, Moderador, Gestor de activos (técnico) o Gestor de activos (comercial) y un inicio de sesión o un token Acceso completo.

El spec de una plantilla:

label es el texto de encabezado de la columna con header=name. Una métrica puede aparecer una sola vez, y una plantilla no contiene consultas en bruto. Cuando se guarda una plantilla, todas las métricas deben ser exportables y deben compartir un paso —con mismatch=sparse, cada una debe ofrecer algún paso—; de lo contrario la respuesta es 422 spec_invalid y params.problems nombra la métrica y el motivo. Una plantilla se ejecuta con su propio mismatch (la aplicación lo muestra como Métricas de otro paso: Estricto o Flexible); el parámetro del enlace de exportación tiene prioridad.

Convertir una plantilla heredada

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

La respuesta enumera mapped (legacy_id, metric, values, exactness: exact o approximate) y unmapped (legacy_id, reason: formula, no_equivalent, report_value o instant, y hasta tres suggestions), y, salvo que fuera una simulación, la nueva template. Una simulación responde 200, una conversión 201.

La plantilla nueva exporta días durante el mes anterior. La plantilla heredada nunca se modifica. Dos columnas heredadas que leen el mismo contador se convierten en una sola columna. 422 nothing_to_convert significa que ninguna columna tiene equivalente, o que la plantilla no es una plantilla heredada.

Límites

Una exportación se responde dentro de una sola solicitud, así que su tamaño está acotado. Cada límite se comprueba antes de leer datos; una solicitud demasiado grande se rechaza de inmediato y te dice qué cabría.

Dividir una exportación grande

400 over_budget nombra en params lo que se necesitaba y lo que está permitido, y en hint la salida: step, el siguiente paso más grueso que cabe, y max_days, el periodo más largo que cabe con el paso solicitado. Consulta primero la estimación si construyes solicitudes en un script; su per_step enumera el tamaño para cada paso.

Si no quieres ni un paso más grueso ni un periodo más corto, divide la exportación:

Algunas métricas se calculan a partir de varias fuentes para cada día, sobre todo plant.production_reported (Producción, resuelta). Necesitan muchas más lecturas del almacén de mediciones que una lectura de contador, con cualquier paso. Una solicitud o una plantilla que lleva una métrica así alcanza actualmente unos nueve meses-planta: una planta durante nueve meses, o nueve plantas durante un mes. Un paso de una semana o más amplía el periodo a intervalos completos, y cuenta el periodo ampliado. Divide estas exportaciones por tiempo o por planta, o exporta la métrica en una solicitud propia.

429 busy y 429 rate_limited llevan el encabezado Retry-After con los segundos que hay que esperar.

Errores

Un error de las rutas de esta página tiene esta forma:

{
  "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 es estable y está pensado para programas. message es un texto en inglés para personas. params indica qué estaba mal, hint qué funcionaría.

401 significa que el token falta, ha caducado o se ha revocado.

Ids de la exportación anterior

El parámetro metrics acepta también los ids de la exportación anterior, como energy_grid_daily o raw_grid_power. Un id con equivalente se traduce a su métrica, en el modo de valores que más se acerca a la cifra anterior, y la nota legacy_id_mapped indica qué métrica respondió y si la cifra es la misma (exact) o la misma magnitud leída de una forma mejor (approximate).

Un id sin equivalente responde 400 legacy_metric_id. hint.reason indica el motivo, hint.closest nombra la métrica más cercana cuando la hay, hint.pending nombra la métrica prevista para sustituirlo, y legacy_url es el enlace de la exportación anterior que sigue entregando el id. Con más plantas de las que puede nombrar un enlace, legacy_url nombra la primera planta y params.legacy_url_scope es first. Un id de componente de un nivel de batería no tiene enlace de la exportación anterior; en ese caso hint.legacy_route es none. La guía de migración enumera todos los ids.

Excel y scripts

• Metric Export para Excel: recetas, y la conexión de Power Query con el encabezado Authorization
• Generador de informes externos: un ejemplo completo en Python

Funciones relacionadas

• Metric Export: la página Exportación de datos
• Migrar a Metric Export: ids antiguos, métricas nuevas y qué cambia
• API de exportación heredada: los enlaces de exportación anteriores
• Métricas: define métricas propias y expórtalas
• Tokens de API: crea el token Metric Export
• Descripción general de la API: la referencia interactiva de todas las rutas