API de pruebas de carga

La API de pruebas de carga permite que un script o un pipeline de CI/CD inicie una prueba de carga guardada, siga la ejecución hasta que termine y lea sus resultados y su veredicto de aprobado o fallo. Funciona con pruebas en la nube, pruebas JMeter y pruebas k6. Primero crea y guarda la prueba en el panel: la API ejecuta una prueba guardada por su nombre.

Autenticación

Cada petición necesita tu clave API y, si perteneces a más de un equipo, el id del equipo al que pertenece la prueba.

Clave API: cópiala o regenérala en la página Claves API (Configuración de la cuenta > Claves API). La clave pertenece a tu usuario y sirve en todos los equipos de los que eres miembro. Trátala como una contraseña.
Id del equipo: la página Equipo predeterminado (Configuración de la cuenta > Equipo predeterminado) muestra el equipo que usan las llamadas a la API que no indican ninguno, con su id, y te permite cambiarlo. La página Developers de Monitoreo de API muestra tu clave API y el id de tu equipo actual uno junto al otro.

Envía la clave en la cabecera loadfocus-auth y el id del equipo en la cabecera team-id. Sin team-id se usa tu equipo predeterminado. Una clave incorrecta, o un equipo del que no eres miembro, recibe 401. Un miembro del equipo sin acceso a las pruebas de carga recibe 403, y también un miembro de solo lectura que intenta iniciar o detener una ejecución o cambiar los umbrales. La API también acepta la clave como parámetro de consulta apikey, pero una cabecera la mantiene fuera de los logs de servidores y proxies.

Qué permite tu plan

Las pruebas en la nube se pueden iniciar desde la API en todos los planes, Load Free incluido.
Las pruebas JMeter y k6 necesitan un plan de pago, o una prueba gratuita de uno, para iniciar una ejecución desde la API. En Load Free la petición se rechaza con 400 y { "error": "Not available on the free plans. Please upgrade for API access." }. En el panel, las cuentas Free pueden seguir ejecutándolas dentro de los límites de Free.
Listar pruebas, leer estados, resultados y veredictos, y definir umbrales funciona en todos los planes.
El plan que cuenta es el del propietario del equipo, como en el panel.

Las ejecuciones iniciadas desde la API cuentan para los mismos límites de ejecuciones que las iniciadas en el panel. Además tienen un tope semanal por tipo de prueba: 10 ejecuciones en Load Free, 5 durante una prueba gratuita (25 en la de Load Starter) y 25 en Load Starter (consulta Planes y límites). Una ejecución rechazada responde 400 con el límite alcanzado, por ejemplo { "error": "number-of-weekly-tests-exceeded", "window": "week", "current": 10, "maximum": 10, "retryAt": "2026-11-12T09:30:00.000Z" }, donde retryAt indica cuándo se permite la siguiente ejecución.

Límites de peticiones

Endpoints de JMeter y k6: 100 peticiones cada 15 minutos por clave API. Iniciar y detener ejecuciones tiene su propio cupo de 100 peticiones cada 5 minutos por clave API.
El endpoint de análisis de resultados de las pruebas en la nube: 100 peticiones cada 15 minutos por clave API.
Cada petición bajo /api/: 10.000 cada 2 minutos por dirección IP.

Si superas un límite, la API responde 429. Consultar el estado de una ejecución cada 30 segundos queda muy por debajo de estos límites.

Endpoints

Todas las rutas empiezan por https://loadfocus.com/api/v1/ seguido del tipo de prueba: loadtests para pruebas en la nube, jmetertests para pruebas JMeter y k6tests para pruebas k6. Una prueba se identifica con testrunname, el nombre con el que la guardaste, y una ejecución con testrunid, su número de ejecución (consulta ¿Qué es un ID de ejecución de prueba?). Codifica el nombre para URL cuando va en una cadena de consulta.

Acción	Método y ruta	Parámetros	Tipos de prueba
Listar tus pruebas, cada una con su última ejecución	`GET /api/v1/{type}/`	ninguno	todos
Iniciar una ejecución de una prueba guardada	`POST /api/v1/{type}/newtest/execute`	`testrunname`	todos
Detener una prueba en curso	`POST /api/v1/{type}/stop`	`testrunname`, `testrunid`	JMeter, k6
Leer el estado de una ejecución	`GET /api/v1/{type}/state`	`testrunname`, `testrunid`	todos
Leer los resultados de una ejecución	`GET /api/v1/{type}/analysis`	`testrunname`, `testrunid`	todos
Leer el veredicto de una ejecución	`GET /api/v1/{type}/verdict`	`testrunname`, `testrunid`	todos
Leer, definir o borrar umbrales	`GET`, `PUT`, `DELETE /api/v1/{type}/thresholds`	`testrunname`; con `PUT`, los límites	todos

Iniciar una ejecución: en las pruebas en la nube envía testrunname en la cadena de consulta; en las pruebas JMeter y k6, como campo de formulario. La respuesta no incluye el número de la nueva ejecución, que se asigna unos segundos después. Anota el último testrunid de la prueba en la lista antes de iniciarla y vuelve a leer la lista hasta que aparezca uno mayor. Para etiquetar la ejecución con la versión que despliegas, espera a que aparezca su número de ejecución y envía testrunname, testrunid, label y, si quieres, url como campos de formulario a POST /api/test/{general|jmeter|k6}/run-annotation (general para las pruebas en la nube), con las mismas cabeceras. releaseTag y releaseUrl en la petición de inicio solo tienen efecto si la petición también lleva un testrunid. Consulta Etiquetas de lanzamiento y anotaciones de ejecución. JMeter y k6 también aceptan POST /api/v1/{type}/execute, que es lo que usa el cliente API de LoadFocus.
Detener: envía testrunname y testrunid como campos de formulario. Una prueba en la nube no se puede detener desde la API; detenla desde el panel.
Estado: state vale running mientras la prueba se ejecuta y finished cuando termina. aborted, error, failed y finished_failed_to_run significan que la ejecución terminó sin resultados.
Resultados: la API de análisis de resultados describe el documento: percentiles, Apdex, tipos de error y cifras por petición y por región.
Veredicto y umbrales: Umbrales de aprobado/fallo describe los límites y el veredicto. Lee el veredicto solo cuando el estado sea finished. Una prueba sin umbrales activados devuelve verdict: "none".

Ejemplos

Inicia una prueba k6 guardada y después una prueba en la nube guardada:

curl -X POST "https://loadfocus.com/api/v1/k6tests/newtest/execute" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID" \
  --data-urlencode "testrunname=checkout-flow"

curl -X POST "https://loadfocus.com/api/v1/loadtests/newtest/execute?testrunname=checkout-flow" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID"

Lee el veredicto de la ejecución 12 de la prueba k6:

curl "https://loadfocus.com/api/v1/k6tests/verdict?testrunname=checkout-flow&testrunid=12" \
  -H "loadfocus-auth: YOUR_API_KEY" -H "team-id: YOUR_TEAM_ID"

Ejecutar una prueba desde GitHub Actions

Este workflow inicia una prueba k6 guardada, espera a que termine la ejecución y hace fallar el job cuando el veredicto es un fallo. Guarda tu clave API y el id de tu equipo como secretos del repositorio LOADFOCUS_API_KEY y LOADFOCUS_TEAM_ID, y define antes los umbrales de aprobado o fallo de la prueba; si no, no hay nada que pueda fallar. Para una prueba en la nube cambia k6tests por loadtests, y para una prueba JMeter por jmetertests.

name: Load test
on:
  workflow_dispatch:

jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - name: Run the saved test and check its verdict
        shell: bash
        env:
          KEY: ${{ secrets.LOADFOCUS_API_KEY }}
          TEAM: ${{ secrets.LOADFOCUS_TEAM_ID }}
          API: https://loadfocus.com/api/v1/k6tests
          TEST: checkout-flow
        run: |
          H=(-sS -H "loadfocus-auth: $KEY" -H "team-id: $TEAM")
          Q=$(jq -rn --arg t "$TEST" '$t|@uri')
          latest() {
            curl "${H[@]}" --fail-with-body "$API/" |
              jq -r --arg t "$TEST" '[.[] | select(.testrunname == $t) | .testrunid | tonumber] | max // 0'
          }

          before=$(latest)
          curl "${H[@]}" --fail-with-body -X POST "$API/newtest/execute?testrunname=$Q" \
            --data-urlencode "testrunname=$TEST"
          echo

          # El número de ejecución se asigna unos segundos después de la petición de inicio.
          id=$before
          for i in $(seq 30); do
            sleep 10
            id=$(latest)
            [ "$id" -gt "$before" ] && break
          done
          [ "$id" -gt "$before" ] || { echo "The run did not start"; exit 1; }

          # Espera hasta 30 minutos a que termine la ejecución.
          state=""
          for i in $(seq 60); do
            state=$(curl "${H[@]}" --fail-with-body "$API/state?testrunname=$Q&testrunid=$id" | jq -r '.state // .teststate // empty')
            echo "Run $id: ${state:-starting}"
            case "$state" in
              finished) break ;;
              aborted|error|failed|finished_failed_to_run) exit 1 ;;
            esac
            sleep 30
          done
          [ "$state" = finished ] || { echo "Timed out"; exit 1; }

          curl "${H[@]}" --fail-with-body "$API/verdict?testrunname=$Q&testrunid=$id" > verdict.json
          jq '{verdict, checks}' verdict.json
          jq -e '.verdict != "fail" and (.enabled == false or (.metricsAvailable and ((.unevaluated // []) | length == 0)))' verdict.json

La última línea también hace fallar el job cuando hay umbrales activados que no se pudieron comprobar, por ejemplo porque la ejecución no registró métricas, así que una ejecución rota nunca pasa en verde.

El cliente API de LoadFocus

El paquete npm @loadfocus/loadfocus-api-client (comando loadfocus-api) solo es compatible con pruebas JMeter. Inicia una prueba JMeter guardada, espera a que termine y compara los resultados con los límites que pasas en la línea de comandos (--thresholds). No tiene comandos para pruebas k6 ni para pruebas en la nube: para esas, llama a la API directamente como se muestra arriba.

Pipelines de JMeter listos para usar con el cliente: