compare_dealsread-only | Compare 2-5 deals side by side (price, unit, offer type, code, verification), best value first. |
compare_gpu_pricesread-only | Compare tracked GPU rental prices for one model (e.g. 'H100', 'A100 SXM', 'RTX 4090', 'L40S'), cheapest first. If a result looks wrong, give the user its report_issue_url.
Same data as https://thelanternworks.com/api/v1/gpu-prices.json. Sorted by hourly_usd ascending; each result
has source_url and checked_at. 'Cheapest' means cheapest among tracked providers, not the whole market.
limit 1-25. Unknown model returns not_found listing tracked models.
H100/A100: cheapest_by_form_factor gives one pick per form_factor (tier_class, interruptible, in_stock); same rule as the site. 'NVLink' rows are form 'not stated': NVLink is the bridge, and the vendor doesn't say SXM or PCIe.
Each result has tier_class: on-demand | community | marketplace | interruptible (spot/preemptible) |
reserved | dedicated-monthly. Reserved (reservation/commitment 'starting from') rates are left out unless
include_reserved=true, and even then they are never reported as cheapest. DEFAULT on_demand_only=true: results[0] is the cheapest
on-demand rate. Pass on_demand_only=false to include spot/interruptible, community and marketplace capacity (each
such row is labelled by tier_class and interruptible); the summary then names the cheapest on-demand rate when the
overall cheapest isn't. If a model has no on-demand rate, or every on-demand rate needs more GPUs than requested,
the default falls back to all rates and says so in on_demand_fallback.
gpus (optional, 1-1024; default 1, stated in assumptions): the GPU count you need. A rate ranks only when its
min_gpus (smallest allocation sold) is <= gpus; rates sold only as larger allocations (e.g. 8-GPU nodes) are NOT
ranked and are listed in excluded_min_gpus (vendor, gpu, tier, min_gpus, gpu_count, hourly_usd, rate_id, source_url,
checked_at, reason, min_bill_usd_per_hour, min_bill_basis); min_gpus_unmet counts them (also in brief). Pass gpus=8 to
compare 8-GPU nodes. If every rate needs more GPUs, the error says which gpus value ranks them.
Each result has min_bill_usd_per_hour = min_gpus x hourly_usd (min_bill_basis: hourly_rate, per_second_rate or
monthly_equivalent) and effective_at, when the vendor started charging this price (effective_at_basis vendor_stated,
or first_observed = first daily snapshot showing it after a different price, an upper bound; null when not datable),
separate from last_verified. Neither affects ranking.
Full results also include batch_due_ledger: each scheduled build (gpu-refresh, lium-collect, scout-import,
scout-wider) has expected_at, last_expected_at, and the member_rate_ids it covers, derived only from the
workflow schedules. Brief mode omits the ledger.
A failed or out-of-stock probe keeps failure_reason (sold_out, region, quota, or other) and
failure_reason_detail; both stay on a lapsed claim next to last_known_in_stock. Null when the source
does not say; never guessed. Display only.
A row with unknown stock, and each stale_prices entry, has next_check_at (next scheduled check, UTC), will_backfill
(true: a scheduled check covers it; false: scope limit, nothing will re-check it; null: not derivable),
backfill_eta and next_check_basis (the schedule it came from).
include_history=true adds each result's price_history (daily-snapshot change points) and history.recent_changes
(price changes for this model among tracked providers, last 30 days) from /api/v1/gpu-prices/history.json.
Each result has data_age_hours (hours since its price was last verified), degraded (> 48 h) and stale (> 7 days).
A degraded row is shown and flagged but never ranked first while a fresh row exists; if none is fresh,
stale_fallback=true and the summary says so.
By default a rate whose price is older than 168 h is never ranked or named cheapest: it is listed in stale_prices
('stale price (N days old)'); if every rate is stale, results is empty and the summary says no current cheapest.
max_data_age_hours (optional) replaces the 168 h default and drops older rates; excluded_too_old counts them.
region (optional): a country/area code ('US', 'EU') matches every published zone in it; a zone code ('US-NE-1', 'us-east-1') matches exactly, any case. Rates whose unexpired published regions exclude it are dropped; rates with no region
evidence stay, labelled unresolved and ranked after the rest. Each result has eligibility {eligible, applied, unmet,
unknown} from the shared T47 contract; constraints.eligible_rate_ids is the same set estimate_job_cost and price
watches use. Unknown stock is not confirmed availability.
Marketplace median rows (price_status=marketplace) also have marketplace_query (the literal filter used for the median, plus structured filters; null when unknown) next to offer_count and lowest_offer_usd, and composition_flag (composition, price, mixed, unknown, or null) from successive median, minimum and listing count only, not a host intersection. A composition, mixed or unknown flag is not a price move. Missing previous min or n stays unknown, never invented. Stale prices stay flagged as stale.
model_identity (T61): sourced nominal_memory and usable_memory (vendor-allocatable) for the queried model, each
with source_url; unknown stays 'unknown'. min_usable_memory_gb (optional) keeps only rows whose SOURCED usable
memory meets it; rows with unknown usable memory are counted in usable_memory_filter.unknown and never matched
on nominal memory or vram_gb. |
create_watch_key | Hosted only, free, opt-in. Register a webhook for GPU price alerts and get an api_key plus a webhook signing secret (both shown ONCE; store them). webhook_url must be public https. email is optional contact only (no mail is sent). No payment. Stored: a hash of the key, the webhook URL, optional email, your watches and per-key counts. |
delete_watch | Hosted only. Delete one of your watches by watch_id. |
estimate_job_costread-only | Cost of one GPU job (not cost per hour) among tracked providers, cheapest current compute subtotal first.
gpu_family (e.g. 'H100', 'A100 80GB') or its alias gpu (same name compare_gpu_prices uses) is required; if both
are given they must match, else invalid_argument. gpus_per_job defaults to 1.
Ranking matches compare_gpu_prices' default: fresh rows first (a degraded price, older than 48 h, is shown and
flagged but never ranked first while a fresh one exists), fresh on-demand before community/marketplace rows,
then compute subtotal ascending; the summary names any cheaper fresh rate ranked lower. If no fresh price exists,
stale_fallback=true and the summary says the top row is not a current price.
You supply the duration: job_hours, OR work_units plus throughput_units_per_gpu_hour from your own benchmark
(job_hours = work_units / (throughput x gpus_per_job)). If you give workload + work_units but no throughput,
a directly applicable published figure (closed-division MLPerf Inference, exact GPU variant, inference only)
is used: throughput_basis='published_benchmark' with throughput_source {url, quote, date, benchmark, derived,
caveats}; your throughput always wins. Otherwise not_found 'missing: throughput for {gpu}'. Whole-instance billing:
instances = ceil(gpus_per_job / gpus_per_instance), all allocated GPUs billed (9 GPUs on an 8-GPU-only
offer bill 16). Reserved and held-stale rates are never ranked; spot/interruptible only if allow_interruptible.
Each result has rate_id, source_url, verified_at, data_age_hours/degraded/stale. Response has assumptions,
citations, missing_costs, budget_verdict (unresolved: extras unknown) and a quote_id. Compute subtotal only. |
get_dealread-only | Get one deal's public record by id, including redeem_url and agent_instructions. |
get_price_changesread-only | GPU rental price changes among tracked providers, each with old/new hourly price, change_pct, direction,
the vendor source_url, a stable event_id (dedupe key) and rate_id.
Marketplace median moves also have composition_flag (composition, price, mixed, unknown, or null) from
successive median, minimum and listing count; composition, mixed and unknown are not price moves.
since: 'YYYY-MM-DD' returns every change on or after that date, newest first (daily snapshots in
/api/v1/gpu-prices/history.json); omitted returns the latest day's moves (/api/v1/gpu-price-changes.json).
cursor: pass next_cursor from a previous call to get every change after it, oldest first, with has_more;
loop until has_more is false, and store next_cursor only after processing (a watcher never misses or repeats
events). error cursor_expired means re-sync with since and dedupe by event_id.
kinds: optional subset of down, up, new, removed, same. gpu: optional model filter (substring, e.g. 'H100').
limit 1-200. Includes data_checked_at and next_refresh_utc (prices refresh daily at about 10:23 UTC). |
list_watchesread-only | Hosted only. Your watches and per-key alert counts. |
optimize_agent_stackread-only | Estimate a monthly stack cost from a short description of the agent being built.
description: free text, e.g. 'scrapes 20k JS pages/month via 5 GB residential proxies, 3k search queries,
summarizes with an LLM, budget $300/mo'. Parsed deterministically (keywords/regex, no LLM) into components:
gpu, scraping, proxy, search, llm_api, email, hosting, database, monitoring. Optional fields override the parse:
gpu_hours (GPU-hours/month), gpu_model ('H100', 'A100', 'RTX 4090'), model_size_b (billions of params; sets a
minimum VRAM using FP16 x 1.2), scrape_pages, js_rendering, proxy_gb, search_queries, emails_sent, llm_api,
monthly_budget_usd. Each component gets the cheapest option with a cited price among tracked providers, with
calc, source_url, verified_at, referral_disclosure (set when the link is a referral link) and manual-signup
notes. Components with no cited price say 'no sourced price tracked' (nothing is estimated). Totals show the
math and say whether they are complete. Pulled listings are excluded. Every option has data_age_hours, degraded (> 48 h) and stale (> 7 days); GPU prices older than 168 h never rank by default (listed in the line's stale_prices); max_data_age_hours replaces that default and drops older options (excluded_too_old counts them). Same data as optimize_stack,
compare_gpu_prices and the deal feed. |
optimize_stackread-only | Cheapest suitable stack among tracked providers for monthly needs (set the quantities you need, rest 0).
scrape_pages: pages/month without JS rendering. scrape_pages_js: pages/month needing JS rendering.
proxy_gb: residential proxy GB/month. emails_sent: transactional emails/month. search_queries: search API
queries/month. gpu_hours: GPU-hours/month (1 GPU), optionally gpu_model e.g. 'H100', 'A100', 'RTX 4090'.
Each line has the chosen plan, monthly_cost_usd, calc, vendor quote, source_url, checked_at and assumptions,
plus alternatives. A vendor price that isn't published is 'unknown' (never estimated). manual_signup_only=true
means a human must sign up (never automate it); exclude_manual_signup=true drops those plans. Same data as
https://thelanternworks.com/api/v1/stack-pricing.json and /tools/stack-optimizer/. |
rebuild_quoteread-only | Reopen a past quote. Pass the `receipt` object returned by optimize_stack, optimize_agent_stack or
estimate_job_cost. Returns receipt_intact (unkeyed sha256 matches), reproduced (true only if each line's subtotal
recomputes AND its rate_id and price match the pinned feed revision or that date's published daily snapshot;
"arithmetic_only" with provenance_verified=false when that can't be confirmed), per-line provenance, and
revalidation against today's feed: per GPU line unchanged | price_changed | evidence_changed | held_today |
not_in_feed_today (flat plans: not_revalidated), with revision 'same' or 'new'. Nothing is re-ranked. |
search_dealsread-only | Search agent work-stack deals (compute, search, email, unblock, hosting...).
offer_type: verified_discount | listed_discount (not confirmed; verified_at null) | free_tier | trial | standard_referral | credit_only_referral.
max_price excludes deals with unknown price. limit 1-25. Pass next_cursor back as cursor to page. |
watch_price | Hosted only. Alert your webhook (signed POST) after the daily refresh when a tracked rate for `gpu` crosses at or below max_hourly_usd, or a change of a watched kind (down/up/new; default down) lands at or below it. Only ELIGIBLE rates match (same contract as compare/estimate): every word of gpu must match the model; 'A100 80GB' or vram_gb=80 never matches a 40GB row; tiers (on-demand, community, marketplace, interruptible/spot, dedicated-monthly, reserved; default all but reserved) never matches another class; a row confirmed sold out never matches (in_stock='require' also skips unknown stock). region: code from availability.available_regions; a rate with no unexpired region evidence stays unresolved and never matches. Each event is delivered at most once per watch (dedupe on event_id). Pass api_key or an Authorization: Bearer header. |