Documentation

AISimulators REST API reference

The REST API is served by AISimulators, the sizing service behind ConfigIQ. It provides GPU recommendation and performance estimation for LLM inference. Interactive docs are at /docs on the service; the OpenAPI spec lives in services/aisimulators/docs/api/openapi.yaml.

Every sizing response reports the simulator that produced it. Optional sections such as memory breakdowns are present only when that simulator supports them; absent means unavailable, never zero.

Endpoints

Method Path Purpose
POST /recommend Find an optimal GPU configuration for a workload
POST /predict Single-point performance estimate for a given parallelism configuration
POST /estimate Deprecated alias for /predict
POST /memory Estimate the GPU memory breakdown for a model configuration
GET /models List supported model architectures
GET /systems List supported GPU systems
GET /backends List supported serving backends and engine versions
GET /networks List network fabrics reported by the serving simulator
GET /simulators List simulators this deployment can run, and the default
GET /metrics Service metrics via content negotiation

Which tool to use for which ask is covered in user scenarios.

Request defaults

Defaults belong to the API, not to the webapp. Only send the values you actually chose; when a field is omitted the service resolves it.

POST /recommend:

Field Default Notes
isl 4000 Input sequence length
osl 1000 Output sequence length
top_n 5 Number of configurations returned. concurrency_capacity returns 8 by default, or 6 when no disaggregated option exists, unless top_n is set explicitly
objective min_gpus Also throughput_demand, concurrency_capacity, pareto
sla_mode enforce none is required by the demand and capacity objectives
ttft / tpot none Required by sla_mode='enforce' unless an end-to-end latency bound is set

objective='min_gpus' with sla_mode='enforce' requires exactly one of target_concurrency or target_request_rate. The demand and capacity objectives have their own requirements, described in the OpenAPI spec.

POST /predict requires a model, a GPU system, and explicit parallelism. It does not search: it evaluates the configuration you give it.

POST /memory requires model_path and system. It is an AISimulate capability; a simulator that does not model memory rejects the request rather than returning an empty breakdown.

Webapp workload presets are not API defaults. Preset names and values come from the deployment's config.json, so a preset is a convenience for filling the form, not a statement about the API contract.

Examples

Recommend a configuration

curl -X POST https://aisimulators.configiq.dev/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "model_path": "meta-llama/Llama-3.1-70B-Instruct",
    "system": "h100_sxm",
    "target_concurrency": 32,
    "ttft": 2000,
    "tpot": 30,
    "isl": 4000,
    "osl": 1000
  }'

Predict performance

curl -X POST https://aisimulators.configiq.dev/predict \
  -H "Content-Type: application/json" \
  -d '{
    "model_path": "meta-llama/Llama-3.1-70B-Instruct",
    "system": "h100_sxm",
    "tp_size": 8,
    "pp_size": 1
  }'

/predict returns TTFT, TPOT, throughput, and a memory breakdown when the simulator provides one. /estimate is the deprecated alias; use /predict in new work.

Estimate memory

curl -X POST https://aisimulators.configiq.dev/memory \
  -H "Content-Type: application/json" \
  -d '{
    "model_path": "meta-llama/Llama-3.1-70B-Instruct",
    "system": "h100_sxm"
  }'

Run the service locally

cd services/aisimulators
uv venv && uv pip install -e . --group dev
uv run uvicorn tools.api_service.app:app --reload --port 7860

The API is then at http://localhost:7860 with interactive docs at http://localhost:7860/docs. The otel and mcp extras are optional:

uv pip install -e '.[otel]'
uv pip install -e '.[mcp]'

Sizing multiple workloads

One call per workload. There is no single mixed-workload endpoint. See user scenarios.

MCP

The sizing and pricing APIs are available as MCP tools. The ConfigIQ MCP gateway presents them with short, stable tool names, and the sizing service can also mount MCP directly with its own generated names. See MCP server for the two shapes.