Reference

HTTP API Endpoints

View as Markdown

When aiperf profile is launched with --api-port <PORT> (or AIPERF_API_SERVER_PORT is set), AIPerf starts an in-process FastAPI server alongside the benchmark and exposes HTTP and Prometheus endpoints for the lifetime of the run. The server is opt-in — if --api-port is not set, no listener is created.

--api-host (default 127.0.0.1) controls the bind address; pass --api-host 0.0.0.0 to expose externally (e.g. in Kubernetes).

The router classes that back these routes live under src/aiperf/api/routers/ and are loaded via the api_router plugin category in plugins.yaml.

Endpoints

MethodPathResponse shapeDescription
GET/api/configBenchmarkConfigDeclarative benchmark configuration for the current run. endpoint.api_key is excluded. Run-identity fields (benchmark_id, cli_command, etc.) live on /api/run, not here.
GET/api/runRunInfoRun-identity metadata: benchmark_id, sweep_id, trial, random_seed, run_label, variation_*, and the redacted cli_command. Same shape as the run_info block in profile_export_aiperf.json.
GET/api/metricsMetricsResponseLive metric values (JSON). Updated as the benchmark progresses.
GET/metricstext/plainPrometheus exposition format. Scrape target for Prometheus and compatible collectors.
GET/api/progressProgressResponsePer-phase credit/request progress.
GET/api/workersWorkersResponsePer-worker stats (request counts, errors, lifecycle state).
GET/api/resultsBenchmarkResultsResponseFinal benchmark results once profiling has completed.
GET/api/results/listResultsListResponseList of result artifact files under the artifact directory.
GET/api/results/files/{filename}file streamDownload an individual artifact file by relative path.
GET/healthztext/plain (ok / unhealthy)Kubernetes liveness probe. 503 when the service is in FAILED state.
GET/readyztext/plain (ok / not ready)Kubernetes readiness probe. 200 only when the service is RUNNING.
GET/docs, /redoc, /openapi.json(FastAPI defaults)Auto-generated OpenAPI documentation.

Breaking change: /api/progress phases keys

ProgressResponse.phases is keyed by each phase’s concrete name (CombinedPhaseStats.phase_name), falling back to the plain CreditPhase value (e.g. "profiling") only when the phase has no explicit name. Prior releases keyed this dict by the closed CreditPhase enum, so progress["phases"]["profiling"] was always a valid lookup. DAG/multi-instance phases now carry user-assigned names, so that fixed lookup can silently miss. Consumers should iterate phases.values() and match on each entry’s phase field instead of indexing by a hardcoded CreditPhase string.

Secret redaction

cli_command is captured from sys.argv at BenchmarkRun construction and redacted by build_cli_command() before it is stored — so the string returned from /api/run and written to profile_export_aiperf.json is the same redacted form. --api-key-shaped flags, credential-bearing --header values (e.g. Authorization: Bearer …), and userinfo embedded in URL-typed flags (--url, -u, --otel-url, --mlflow-tracking-uri) are all scrubbed to <redacted>.

/api/config independently excludes endpoint.api_key from its response.

Example

$aiperf profile --model my-model --url http://localhost:8000 \
>    --api-key sk-secret-12345 --api-port 9097 --request-count 1000 &
$
$# Inspect the redacted launch command
$curl -s http://127.0.0.1:9097/api/run | jq .cli_command
$# "aiperf profile --model 'my-model' --url 'http://localhost:8000' \
>#  --api-key '<redacted>' --api-port 9097 --request-count 1000"
$
$# Liveness probe
$curl -s http://127.0.0.1:9097/healthz
$# ok