Endpoint de Consulta de Experimentos

El endpoint /api/experiments/query permite obtener datos estadísticos y de rendimiento sobre los experimentos en ejecución o completados. Proporciona métricas detalladas sobre exposiciones, conversiones, tasas de mejora y significancia estadística para facilitar la toma de decisiones basada en datos.

Especificación de la API

URL: /api/experiments/query
Método: GET
Formato de respuesta: JSON
Autenticación: API Key en encabezado X-SA-API-KEY

Parámetros de la Solicitud

Parámetro	Tipo	Ubicación	Requerido	Descripción
`site_id`	string	Query	Sí	Identificador único del sitio
`experiment_id`	string	Query	No	ID del experimento (si se omite, se devuelven todos los experimentos)
`start_date`	string	Query	No	Fecha de inicio para filtrar datos (formato ISO: “YYYY-MM-DD”)
`end_date`	string	Query	No	Fecha de fin para filtrar datos (formato ISO: “YYYY-MM-DD”)
`metrics`	string	Query	No	Lista separada por comas de métricas a incluir
`segment_id`	string	Query	No	Filtrar por segmento específico
`goal_ids`	string	Query	No	Lista separada por comas de IDs de metas a incluir
`include_variations`	boolean	Query	No	Si se deben incluir datos por variante (por defecto: true)
`confidence_level`	number	Query	No	Nivel de confianza para la significancia estadística (por defecto: 0.95)

Ejemplo de URL


/api/experiments/query?site_id=site_123abc&experiment_id=exp_12345&start_date=2023-06-01&end_date=2023-07-01&metrics=conversion_rate,average_value&include_variations=true

Respuesta

La respuesta incluye datos estadísticos detallados sobre el experimento:


{
  "experiment": {
    "experiment_id": "exp_12345",
    "name": "Prueba de botón CTA",
    "status": "completed",
    "type": "a/b_test",
    "start_date": "2023-06-01T00:00:00Z",
    "end_date": "2023-07-01T00:00:00Z",
    "total_exposures": 15642,
    "total_conversions": 876,
    "conversion_rate": 0.056,
    "average_value": 78.45,
    "winning_variation": "var_b",
    "statistical_significance": 0.98,
    "metrics_summary": {
      "conversion_rate": {
        "lift": 0.232,
        "p_value": 0.016,
        "confidence": 0.984,
        "is_significant": true
      },
      "average_value": {
        "lift": 0.116,
        "p_value": 0.042,
        "confidence": 0.958,
        "is_significant": true
      }
    },
    "variations": [
      {
        "variation_id": "var_a",
        "name": "Control (original)",
        "is_control": true,
        "exposures": 7825,
        "conversions": 391,
        "conversion_rate": 0.05,
        "average_value": 72.30,
        "metrics": {
          "conversion_rate": {
            "value": 0.05,
            "baseline": true
          },
          "average_value": {
            "value": 72.30,
            "baseline": true
          }
        }
      },
      {
        "variation_id": "var_b",
        "name": "Botón rojo",
        "is_control": false,
        "exposures": 7817,
        "conversions": 485,
        "conversion_rate": 0.062,
        "average_value": 80.68,
        "metrics": {
          "conversion_rate": {
            "value": 0.062,
            "lift": 0.24,
            "p_value": 0.016,
            "confidence": 0.984,
            "is_significant": true
          },
          "average_value": {
            "value": 80.68,
            "lift": 0.116,
            "p_value": 0.042,
            "confidence": 0.958,
            "is_significant": true
          }
        }
      }
    ],
    "goals": [
      {
        "goal_id": "goal_1",
        "name": "Compra completada",
        "is_primary": true,
        "total_conversions": 876
      },
      {
        "goal_id": "goal_2",
        "name": "Clic en botón",
        "is_primary": false,
        "total_conversions": 2543
      }
    ]
  },
  "site_id": "site_123abc"
}

Múltiples experimentos

Cuando se omite el parámetro experiment_id, la respuesta incluye datos resumidos para todos los experimentos:


{
  "experiments": [
    {
      "experiment_id": "exp_12345",
      "name": "Prueba de botón CTA",
      "status": "completed",
      "type": "a/b_test",
      "start_date": "2023-06-01T00:00:00Z",
      "end_date": "2023-07-01T00:00:00Z",
      "total_exposures": 15642,
      "total_conversions": 876,
      "conversion_rate": 0.056,
      "winning_variation": "var_b",
      "statistical_significance": 0.98
    },
    {
      "experiment_id": "exp_67890",
      "name": "Personalización de página de inicio",
      "status": "active",
      "type": "personalization",
      "start_date": "2023-05-15T00:00:00Z",
      "total_exposures": 23487,
      "total_conversions": 1254,
      "conversion_rate": 0.053,
      "winning_variation": null,
      "statistical_significance": 0.82
    }
  ],
  "count": 2,
  "site_id": "site_123abc"
}

Métricas disponibles

Métrica	Descripción
`exposures`	Número total de exposiciones
`conversions`	Número total de conversiones
`conversion_rate`	Tasa de conversión (conversiones / exposiciones)
`average_value`	Valor promedio por conversión
`total_value`	Valor total de todas las conversiones
`bounce_rate`	Tasa de rebote
`time_on_page`	Tiempo promedio en la página
`sessions_per_user`	Sesiones promedio por usuario
`page_views_per_session`	Vistas de página por sesión
`custom_event_count`	Conteo de eventos personalizados

Filtrado por segmentos

Puede filtrar los resultados para un segmento específico usando el parámetro segment_id:


/api/experiments/query?site_id=site_123abc&experiment_id=exp_12345&segment_id=seg_mobile_users

Esto devolverá los resultados del experimento solo para los visitantes que pertenecen al segmento especificado.

Series temporales

Para obtener datos de series temporales que muestren el rendimiento a lo largo del tiempo, añada el parámetro time_series=true:


/api/experiments/query?site_id=site_123abc&experiment_id=exp_12345&time_series=true&interval=daily

La respuesta incluirá datos agrupados por intervalos de tiempo:


{
  "experiment": {
    "experiment_id": "exp_12345",
    "name": "Prueba de botón CTA",
    "time_series": {
      "interval": "daily",
      "data": [
        {
          "date": "2023-06-01",
          "variations": {
            "var_a": {
              "exposures": 254,
              "conversions": 12,
              "conversion_rate": 0.047
            },
            "var_b": {
              "exposures": 261,
              "conversions": 15,
              "conversion_rate": 0.057
            }
          }
        },
        {
          "date": "2023-06-02",
          "variations": {
            "var_a": {
              "exposures": 278,
              "conversions": 14,
              "conversion_rate": 0.050
            },
            "var_b": {
              "exposures": 273,
              "conversions": 17,
              "conversion_rate": 0.062
            }
          }
        }
      ]
    }
  }
}

Explicación estadística

Para incluir una explicación detallada de los resultados estadísticos en lenguaje natural, añada el parámetro include_explanation=true:


/api/experiments/query?site_id=site_123abc&experiment_id=exp_12345&include_explanation=true

La respuesta incluirá un campo adicional con la explicación:


{
  "experiment": {
    "experiment_id": "exp_12345",
    "name": "Prueba de botón CTA",
    "statistical_explanation": "La variante B muestra un incremento del 24% en la tasa de conversión comparado con la variante de control. Este resultado es estadísticamente significativo con un 98.4% de confianza, lo que significa que hay solo un 1.6% de probabilidad de que este resultado se deba al azar. Recomendamos implementar la variante B dado que ha demostrado una mejora significativa."
  }
}

Códigos de estado HTTP

200 OK: Solicitud exitosa
400 Bad Request: Parámetros inválidos
401 Unauthorized: API key inválida o faltante
403 Forbidden: El sitio no tiene permisos para usar experimentos
404 Not Found: Experimento no encontrado
429 Too Many Requests: Se ha excedido el límite de peticiones
500 Internal Server Error: Error en el servidor

Exportación de datos

Para exportar los datos en un formato específico, use el parámetro format:


/api/experiments/query?site_id=site_123abc&experiment_id=exp_12345&format=csv

Formatos disponibles:

json (por defecto)
csv
excel

Implementación en el script de tracking


// Función para obtener resultados de experimentos
siteAnalyzer.queryExperiment = function(experimentId, options = {}) {
  const queryParams = new URLSearchParams({
    site_id: this.siteId,
    experiment_id: experimentId,
    ...options
  });
  
  return fetch(`/api/experiments/query?${queryParams.toString()}`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'X-SA-API-KEY': this.apiKey
    }
  })
  .then(response => response.json());
};
 
// Ejemplo de uso
siteAnalyzer.queryExperiment('exp_12345', {
  start_date: '2023-06-01',
  end_date: '2023-07-01',
  metrics: 'conversion_rate,average_value',
  include_variations: true
}).then(data => {
  console.log('Resultados del experimento:', data);
});

Límites y cuotas

Peticiones por minuto: 60 por IP
Tamaño máximo de respuesta: 10MB
Máximo de días en series temporales: 366 (1 año)