Compute Advisor API

01 · QUICKSTART

One POST. No interview.

The Advisor always returns a terminal response. If your description omits traffic, context length, precision, or another required input, the API selects a documented default and includes it in assumption_banner.

cURL

curl https://skyportal.ai/advisor/advise/ \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Llama 3.3 70B at 50,000 requests/hour at peak",
    "mode": "model"
  }'

02 · REQUEST

Request body

descriptionstring · required

Plain-English model, workload, current fleet, use case, or budget. Include any facts you already know.

modestring · optional

One of plan, model, existing, or budget. The advisor infers the mode when omitted.

verboseboolean · optional

Set to true to return the full configuration ladder instead of the top five options.

03 · MODES

Four ways in

model

Requirements first

Returns memory requirements by precision for a named model.

existing

Audit a fleet

Compares a current GPU configuration and rate with a right-sized plan.

plan

Plan a workload

Builds a practical baseline from a model, users, or use case.

budget

Evaluate in reverse

Finds the largest catalog model and best precision the stated budget affords.

04 · RESPONSE

A complete plan

Successful requests return HTTP 200 and status: "complete".

analysis_idUUID

The persisted analysis identifier used to carry this result into report experiences.

spec_so_farobject

Normalized model, traffic, token lengths, precision, and current configuration with provenance.

assumption_bannerarray

Every approximated or defaulted workload input, ready to expose in your UI.

recommendation_setobject

Memory requirement, ranked options, verdict, confidence, current spend, and savings.

price_freshnessstring

Whether the prices are live, stale, fallback, or unavailable.

200 · application/json

{
  "status": "complete",
  "analysis_id": "bd25aa21-6497-45df-879c-d23a05afe1af",
  "spec_so_far": {
    "mode": "existing",
    "model": { "value": "llama-3.3-70b", "source": "inferred" },
    "weight_precision": { "value": "fp8", "source": "defaulted" }
  },
  "assumption_banner": ["~1,000-token responses"],
  "price_freshness": "live",
  "recommendation_set": {
    "requirement": { "total_required_bytes": 280100000000 },
    "options": [{
      "gpu_id": "h200", "gpu_count": 4,
      "headroom_fraction": 0.46,
      "monthly_cost": 5840,
      "labels": ["best"]
    }],
    "current_monthly_cost": 16936,
    "current_cost_is_estimated": false,
    "savings_per_year": 133152
  }
}

Savings need your price

savings_per_year is returned only when you send currentPricePerGpuHour. Without it we price your current hardware at market rate, return current_cost_is_estimated: true, and report no saving — we will not measure you against a price we made up.

05 · EXAMPLES

Use it anywhere

JavaScript

const response = await fetch(
  "https://skyportal.ai/advisor/advise/",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      description: "budget $3,000/mo",
      mode: "budget"
    })
  }
);

const plan = await response.json();

Python

import requests

plan = requests.post(
    "https://skyportal.ai/advisor/advise/",
    json={
        "description": "budget $3,000/mo",
        "mode": "budget",
    },
    timeout=30,
).json()

06 · ERRORS

Errors are explicit

400Invalid request

Malformed JSON, missing description, or an unsupported mode.

405Method not allowed

The endpoint accepts POST requests only.

Preview authentication

The endpoint is public during preview. Versioned API keys, quotas, and provider-level price freshness fields will be added before a stable /v1 release.

Compute advice,
one request away.