Endpoints de posiciones históricas de ETF: instantáneas de la composición por fecha de reporte

Los datos de posiciones de un ETF describen la composición de un fondo en una fecha concreta: qué valores contenía, en qué cantidades y con qué ponderaciones en la cartera. A diferencia de una instantánea actual, los registros históricos permiten seguir los cambios de composición a lo largo del tiempo, comparar el estado del fondo entre periodos o reconstruir posiciones de la cartera en fechas determinadas para flujos de trabajo cuantitativos y basados en IA. La FinImpulse API ofrece ahora acceso programático a estos datos en todas las fechas de reporte disponibles.

Flujo de trabajo con dos endpoints

La recuperación de datos históricos de posiciones sigue una secuencia de dos pasos. La primera solicitud determina qué fechas están disponibles para el ETF seleccionado; la segunda recupera la composición real para la fecha elegida.

Paso 1: recuperar las fechas de reporte disponibles

El endpoint v1/holdings/history/dates/{symbol} devuelve la lista de fechas para las que existen datos de posiciones del ETF solicitado. El símbolo se pasa como parámetro de ruta; un parámetro opcional start_date filtra los resultados para devolver solo las fechas iguales o posteriores a un valor especificado.

{
  "start_date": "2026-05-17",
  "limit": 3,
  "offset": 0
}

La respuesta devuelve una lista paginada de las fechas de reporte disponibles:

"result": {
        "total_count": 7,
        "items_count": 3,
        "items": [
            {
                "type": "date",
                "history_date": "2026-05-18"
            },
            {
                "type": "date",
                "history_date": "2026-05-19"
            },
            {
                "type": "date",
                "history_date": "2026-05-21"
            }
        ]
    }

Paso 2: recuperar la instantánea de posiciones

Una vez confirmada una fecha de reporte válida, el endpoint v1/holdings/history devuelve la composición completa de la cartera para esa fecha.

Si se intenta consultar las posiciones sin una fecha de reporte válida — una que exista en el conjunto de datos de ese símbolo —, se devolverá un resultado vacío.

La solicitud requiere dos parámetros: symbol y date.

{
  "symbol": "SPY",
  "date": "2026-04-26"
}

La respuesta devuelve un array paginado de registros de posiciones, cada uno de los cuales representa una posición individual en la composición del fondo en la fecha solicitada:

"result": {
        "total_count": 502,
        "items_count": 10,
        "items": [
            {
                "asset": "AAPL",
                "name": "APPLE INC",
                "isin": "US0378331005",
                "cusip": "037833100",
                "shares": 174355685,
                "weight_pct": 6.576,
                "market_value": 47676787718,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            {
                "asset": "ABNB",
                "name": "AIRBNB INC CLASS A",
                "isin": "US0090661010",
                "cusip": "009066101",
                "shares": 5019960,
                "weight_pct": 0.098,
                "market_value": 712219924,
                "updated_at": "2026-04-26T02:04:23Z"
            },
            ...
        ]
  }

La referencia completa de parámetros de ambos endpoints está disponible en la documentación de la API de FinImpulse.

Cobertura y disponibilidad

Los datos históricos de posiciones están disponibles actualmente para aproximadamente 8.000 símbolos de ETF. La cobertura comienza el 1 de enero de 2026 para la mayoría de los símbolos; un subconjunto de unos 500 ETFs cuenta con registros que se remontan a 2023–2025.

La lista completa de los símbolos cubiertos, con las fechas de inicio y de fin de cada uno, está disponible para su descarga aquí.

Casos de uso de los datos históricos de posiciones de ETFs

Los datos históricos de posiciones de ETFs son directamente aplicables a una amplia gama de flujos de trabajo analíticos, cuantitativos y de ingeniería.

Seguimiento de la composición a lo largo del tiempo

La aplicación más directa de estos endpoints es seguir cómo han cambiado las posiciones de un ETF entre las fechas de reporte. Al consultar el mismo símbolo en varias fechas —obtenidas mediante el endpoint de fechas—, es posible construir una vista de serie temporal de los cambios de composición: qué posiciones se añadieron, se eliminaron o se reponderaron entre periodos. Esto es relevante para cualquier flujo de trabajo que trate la composición del ETF como una variable dinámica y no como una instantánea estática.

Detección de solapamiento de posiciones

Al comparar dos o más ETFs, los datos de posiciones de una fecha específica proporcionan la información necesaria para calcular el grado de solapamiento: la proporción de posiciones compartidas, ya sea por ponderación o por número. Esto es relevante en los flujos de trabajo de comparación de fondos en los que el riesgo de concentración entre fondos correlacionados es una preocupación.

Reconstrucción del estado histórico para modelos cuantitativos

Muchos flujos de trabajo cuantitativos requieren saber qué mantenía un fondo en una fecha pasada concreta, en lugar de qué mantiene en la actualidad. El backtesting de un modelo que implique replicación de ETFs, por ejemplo, depende de datos históricos de composición precisos, y no de las posiciones actuales aplicadas retroactivamente. Estos endpoints proporcionan las instantáneas fechadas necesarias para reconstruir el estado de una cartera en un momento determinado sin aproximaciones.

Herramientas de análisis y comparación de ETFs

Para los desarrolladores y equipos que crean páginas de detalle de ETFs, vistas de comparación de fondos o herramientas de análisis de carteras, estos endpoints proporcionan la capa de datos para desgloses de posiciones, visualizaciones de la ponderación de las posiciones y filtrado basado en la composición.

El endpoint de posiciones admite el filtrado y la ordenación en el servidor —por umbral de ponderación, tamaño de la posición u otros campos disponibles—, lo que reduce el volumen de datos transferidos y el procesamiento necesario en el lado del cliente.

Flujos de trabajo de investigación con IA

Las instantáneas de posiciones pueden servir de entrada estructurada para agentes de IA y pipelines de modelos de lenguaje que operan con datos financieros. Un agente que evalúe el comportamiento de un fondo en una fecha específica, genere un resumen de las principales posiciones o compare la composición de dos fondos puede usar estos endpoints para recuperar datos precisos correspondientes a esa fecha, en lugar de depender de aproximaciones.

En estos flujos de trabajo, los dos endpoints constituyen ahora la capa de datos para cualquier tarea que requiera la composición de un ETF en un momento concreto: desde la detección de solapamientos y el backtesting hasta los pipelines de investigación con IA.