Lasttest-API

Mit der Lasttest-API startet ein Skript oder eine CI/CD-Pipeline einen gespeicherten Lasttest, verfolgt den Lauf bis zum Ende und liest seine Ergebnisse und sein Pass/Fail-Verdict. Sie funktioniert für Cloud-Tests, JMeter-Tests und k6-Tests. Legen Sie den Test zuerst im Dashboard an und speichern Sie ihn: Die API führt einen gespeicherten Test über seinen Namen aus.

Authentifizierung

Jede Anfrage braucht Ihren API-Schlüssel und, wenn Sie mehreren Teams angehören, die ID des Teams, dem der Test gehört.

API-Schlüssel: Kopieren oder regenerieren Sie ihn auf der Seite API-Schlüssel (Kontoeinstellungen > API-Schlüssel). Der Schlüssel gehört zu Ihrem Benutzer und gilt in jedem Team, in dem Sie Mitglied sind. Behandeln Sie ihn wie ein Passwort.
Team-ID: Die Seite Standardteam (Kontoeinstellungen > Standardteam) zeigt das Team, das API-Aufrufe ohne Teamangabe verwenden, mit seiner ID, und dort können Sie es ändern. Die Developers-Seite im API-Monitoring zeigt Ihren API-Schlüssel und die ID Ihres aktuellen Teams nebeneinander.

Senden Sie den Schlüssel im Header loadfocus-auth und die Team-ID im Header team-id. Ohne team-id wird Ihr Standardteam verwendet. Ein falscher Schlüssel oder ein Team, in dem Sie nicht Mitglied sind, ergibt 401. Ein Teammitglied ohne Zugriff auf Lasttests erhält 403, ebenso ein Mitglied mit Nur-Lese-Zugriff, das einen Lauf starten oder stoppen oder Schwellenwerte ändern will. Die API akzeptiert den Schlüssel auch als Query-Parameter apikey, aber ein Header hält ihn aus Server- und Proxy-Logs heraus.

Was Ihr Tarif erlaubt

Cloud-Tests lassen sich in jedem Tarif über die API starten, auch in Load Free.
JMeter- und k6-Tests brauchen einen bezahlten Tarif oder dessen Testphase, um einen Lauf über die API zu starten. In Load Free wird die Startanfrage mit 400 und { "error": "Not available on the free plans. Please upgrade for API access." } abgelehnt. Im Dashboard können Free-Konten sie weiterhin innerhalb der Free-Limits ausführen.
Tests auflisten, Status, Ergebnisse und Verdicts lesen sowie Schwellenwerte setzen funktioniert in jedem Tarif.
Es zählt der Tarif des Teaminhabers, wie im Dashboard.

Über die API gestartete Läufe zählen gegen dieselben Laufgrenzen wie Läufe aus dem Dashboard. Zusätzlich gilt eine wöchentliche Obergrenze je Testart: 10 Läufe bei Load Free, 5 während einer Testphase (25 in einer Testphase von Load Starter) und 25 bei Load Starter (siehe Tarife und Limits). Ein abgelehnter Lauf antwortet mit 400 und dem erreichten Limit, zum Beispiel { "error": "number-of-weekly-tests-exceeded", "window": "week", "current": 10, "maximum": 10, "retryAt": "2026-11-12T09:30:00.000Z" }. retryAt ist der Zeitpunkt, ab dem der nächste Lauf erlaubt ist.

Ratenlimits

JMeter- und k6-Endpunkte: 100 Anfragen pro 15 Minuten je API-Schlüssel. Das Starten und Stoppen von Läufen hat ein eigenes Kontingent von 100 Anfragen pro 5 Minuten je API-Schlüssel.
Der Endpunkt für die Ergebnisanalyse von Cloud-Tests: 100 Anfragen pro 15 Minuten je API-Schlüssel.
Jede Anfrage unter /api/: 10.000 pro 2 Minuten je IP-Adresse.

Über einem Limit antwortet die API mit 429. Wenn Sie den Status eines Laufs alle 30 Sekunden abfragen, bleiben Sie deutlich darunter.

Endpunkte

Alle Pfade beginnen mit https://loadfocus.com/api/v1/, gefolgt von der Testart: loadtests für Cloud-Tests, jmetertests für JMeter-Tests und k6tests für k6-Tests. Ein Test wird über testrunname benannt, den Namen, unter dem Sie ihn gespeichert haben, ein Lauf über testrunid, seine Laufnummer (siehe Was ist eine Testlauf-ID?). Kodieren Sie den Namen für die URL, wenn er in einem Query-String steht.

Aktion	Methode und Pfad	Parameter	Testarten
Ihre Tests auflisten, jeweils mit dem letzten Lauf	`GET /api/v1/{type}/`	keine	alle
Einen gespeicherten Test starten	`POST /api/v1/{type}/newtest/execute`	`testrunname`	alle
Einen laufenden Test stoppen	`POST /api/v1/{type}/stop`	`testrunname`, `testrunid`	JMeter, k6
Den Status eines Laufs lesen	`GET /api/v1/{type}/state`	`testrunname`, `testrunid`	alle
Die Ergebnisse eines Laufs lesen	`GET /api/v1/{type}/analysis`	`testrunname`, `testrunid`	alle
Das Pass/Fail-Verdict eines Laufs lesen	`GET /api/v1/{type}/verdict`	`testrunname`, `testrunid`	alle
Schwellenwerte lesen, setzen oder löschen	`GET`, `PUT`, `DELETE /api/v1/{type}/thresholds`	`testrunname`; bei `PUT` die Limits	alle

Lauf starten: Bei Cloud-Tests senden Sie testrunname im Query-String, bei JMeter- und k6-Tests als Formularfeld. Die Antwort enthält die neue Laufnummer nicht, sie wird einige Sekunden später vergeben. Merken Sie sich vor dem Start die letzte testrunid des Tests aus der Liste und lesen Sie die Liste dann erneut, bis eine höhere erscheint. Um den Lauf mit der ausgerollten Version zu versehen, warten Sie, bis seine Laufnummer erscheint, und senden Sie dann testrunname, testrunid, label und optional url als Formularfelder an POST /api/test/{general|jmeter|k6}/run-annotation (general für Cloud-Tests), mit denselben Headern. releaseTag und releaseUrl in der Startanfrage wirken nur, wenn die Anfrage auch eine testrunid enthält. Siehe Release-Tags und Run-Annotationen. JMeter und k6 akzeptieren auch POST /api/v1/{type}/execute, das der LoadFocus API Client verwendet.
Stoppen: Senden Sie testrunname und testrunid als Formularfelder. Ein Cloud-Test lässt sich nicht über die API stoppen; stoppen Sie ihn im Dashboard.
Status: state ist running, solange der Test läuft, und finished, wenn er fertig ist. aborted, error, failed und finished_failed_to_run bedeuten, dass der Lauf ohne Ergebnisse endete.
Ergebnisse: Die Ergebnisanalyse-API beschreibt das Dokument: Perzentile, Apdex, Fehlertypen, Kennzahlen pro Request und pro Region.
Verdict und Schwellenwerte: Pass/Fail-Schwellenwerte beschreibt die Limits und das Verdict. Lesen Sie das Verdict erst, wenn der Status finished ist. Ein Test ohne aktivierte Schwellenwerte liefert verdict: "none".

Beispiele

Einen gespeicherten k6-Test starten, dann einen gespeicherten Cloud-Test:

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"

Das Verdict von Lauf 12 des k6-Tests lesen:

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"

Einen Test aus GitHub Actions ausführen

Dieser Workflow startet einen gespeicherten k6-Test, wartet auf das Ende des Laufs und lässt den Job scheitern, wenn das Verdict ein Fail ist. Speichern Sie Ihren API-Schlüssel und Ihre Team-ID als Repository-Secrets LOADFOCUS_API_KEY und LOADFOCUS_TEAM_ID und legen Sie vorher Pass/Fail-Schwellenwerte für den Test fest, sonst gibt es nichts, woran er scheitern kann. Für einen Cloud-Test ändern Sie k6tests in loadtests, für einen JMeter-Test in 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

          # Die Laufnummer wird einige Sekunden nach der Startanfrage vergeben.
          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; }

          # Bis zu 30 Minuten auf das Ende des Laufs warten.
          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

Die letzte Zeile lässt den Job auch scheitern, wenn Schwellenwerte aktiviert sind, aber nicht geprüft werden konnten, etwa weil der Lauf keine Metriken aufgezeichnet hat. So geht ein fehlerhafter Lauf nie als grün durch.

Der LoadFocus API Client

Das npm-Paket @loadfocus/loadfocus-api-client (Befehl loadfocus-api) unterstützt nur JMeter-Tests. Es startet einen gespeicherten JMeter-Test, wartet auf sein Ende und vergleicht die Ergebnisse mit Limits, die Sie auf der Kommandozeile übergeben (--thresholds). Für k6- und Cloud-Tests hat es keine Befehle: Rufen Sie dafür die API direkt auf, wie oben gezeigt.

Fertige JMeter-Pipelines mit dem Client: