ドキュメントのセクション

シミュレーションジョブ

計算ツールは 1 回のリクエストで答えます。シミュレーターはそうではない（フルウェーブの解析には数分から数時間かかる）ため、ジョブとして投入してポーリングします。各ジョブタイプは /api/py/v1/jobs/types でパラメーター契約を公開しています。すべてのパラメーターの型、単位、範囲または選択肢、既定値、必須かどうか、そしてご利用のプランの制限です。ブラウザーのフォームはこのドキュメントから作られ、ワーカーもこれに照らして検証します。パラメーター名はこのページから書き写さず、このドキュメントを読んでください。

エンドポイント

ジョブのエンドポイント
エンドポイント	内容	認証情報
GET /api/py/v1/jobs/types	すべてのシミュレーションジョブタイプと、そのプラン、時間上限、制限、アップロード。	不要
GET /api/py/v1/jobs/types/{job_type}	1 つのジョブタイプのパラメーター契約（JSON Schema）。	不要
POST /api/py/v1/jobs/estimate	ジョブを投入せずに、その費用と所要時間を見積もります。	不要
POST /api/py/v1/upload	ジョブの入力ファイル用の署名付きフォーム。	API キーまたはログイン中のセッション
POST /api/py/v1/jobs	シミュレーションジョブを投入します。	任意：API キー
GET /api/py/v1/jobs/{job_id}	ジョブのステータスと進捗、完了後は結果へのリンク。	投入したときと同じ身元
GET /api/py/v1/jobs	アカウントのすべてのキーで投入した、呼び出し元の最近のジョブ。	API キーまたはログイン中のセッション

投入とポーリング

契約を読み、params（アップロードしたファイルがあれば inputFileKeys も）を付けてジョブを POST すると、jobId 付きの 202 が返ります。キーを使った場合、投入は利用枠に対する 1 回の呼び出しとして計上されます。

投入したときと同じ身元で GET /api/py/v1/jobs/{jobId} をポーリングします。ステータスには progress、stage、finishedAt、elapsedSeconds、errorKind が含まれ、完了すると署名付きの resultUrl が加わります。GET /api/py/v1/jobs は、アカウントのどのキーで投入したものも含め、最近のジョブを一覧にします。Python ライブラリはウェブアプリと同じ方法でポーリングします。job.wait() はすぐに確認し、その後ジョブが続く間は 2 秒、5 秒、15 秒ごとに確認します。

ジョブタイプ

ジョブタイプは 13 種です。各タイプのパラメーター一覧は /api/py/v1/jobs/types/{jobType} にあります。

ジョブタイプ
jobType	シミュレーター	アップロード
`antenna_sim`パラメーター 14 個	ワイヤーアンテナシミュレーター (NEC-2)	なし
`emi_radiated`パラメーター 11 個	EMI 放射エミッション推定器	なし
`eye_diagram`パラメーター 11 個	Sパラメータからのアイダイアグラム	必須、最大 1 × .s2p / .s4p
`fdtd_sparam`パラメーター 17 個	FDTD 伝送ラインシミュレータ	なし
`filter_monte_carlo`パラメーター 15 個	RF フィルターモンテカルロ解析	なし
`impedance_match`パラメーター 14 個	広帯域インピーダンスマッチングシンセサイザー	任意、最大 2 × .s2p / .s1p
`magnetics_optimizer`パラメーター 14 個	磁気および変圧器設計オプティマイザー	なし
`pdn_impedance`パラメーター 16 個	PDN インピーダンス・アナライザおよびデカップリング・キャパシタ・オプティマイザ	なし
`radar_detection`パラメーター 15 個	レーダー探知性能モンテカルロ	なし
`rf_cascade`パラメーター 8 個	RF カスケードバジェットアナライザ	任意、最大 12 × .s2p
`sat_link_budget`パラメーター 14 個	衛星および地上波リンク予算	なし
`smps_control_loop`パラメーター 36 個	SMPS制御ループ安定性アナライザー	なし
`sparam_pipeline`パラメーター 3 個	Sパラメータ分析パイプライン	必須、最大 4 × .s1p / .s2p / .s3p / .s4p

ジョブの費用の見積もり

POST /api/py/v1/jobs/estimate は投入時と同じボディを受け取り、そのジョブが実行される実行環境、想定される所要時間、その環境の予算に収まるか、さらに有料の実行環境では記録されるクレジットを返します。見積もりは課金されず、キーも不要で、投入時と同じチェックを行うため、投入が拒否される場合にのみ拒否されます。クレジットは表示・記録されますが、まだ課金はされません。

リクエストが拒否される場合

投入は、キューに入れたり課金したりする前に契約に照らしてチェックされます。契約外のリクエストには、最初に見つかったものだけでなく、問題のあるすべてのパラメーターを示す 400 が返り、キューにも入らず、利用枠も消費されません。不明なパラメーターキーは無視されず、拒否されます。

エラーの種類

すべての失敗には、メッセージと並んで errorKind が付きます。拒否された投入でも、受理後に失敗したジョブでも同じです。これは閉じた値の集合です。メッセージの文言は人が読むためのもので変わることがあるため、文言ではなくこれで分岐させてください。

エラーの種類
errorKind	意味
invalid_request	パラメーターが欠けている、型が違う、範囲外である、宣言された選択肢にない、またはこのジョブタイプのパラメーターではありません。400 のボディに、問題のあるすべてのパラメーターが示されます。
too_large	リクエストは契約の範囲内ですが、このプランの実行環境で実行できる規模を超えています。問題の規模を小さくしてください。
not_available	リクエストが、このプランに含まれないモードや機能を求めています。メッセージに、プランに含まれるものが示されます。
rate_limited	同時実行ジョブの上限に達したか、月間利用枠を使い切りました。Retry-After が付き、月間利用枠の場合は resetAt も付きます。
timeout	ジョブがそのタイプの時間上限を超えました。課金はされません。
interrupted	実行が完了前に止まりました（ワーカーが置き換えられたか、タスクが停止されました）。課金はされません。
result_expired	ジョブは完了しましたが、結果はもう保存されていません。ステータスは completed のままで、resultUrl はありません。
transient	サービスがその時点でリクエストを受け付けられなかったか、確認できませんでした。キューにも入っておらず、課金もされていません。もう一度お試しください。
fault	計算中にサービスが失敗しました。メッセージに失敗した段階が示されます。課金はされません。

制限、重複、保存期間

同時実行

呼び出し元ごとに、キュー待ちまたは実行中のジョブは同時に 3 件までです。超えると API は Retry-After と、pending と limit を含むボディ付きで 429 を返します。

重複した投入

同じ呼び出し元から 60 秒以内に同一のリクエストが来ると、既存のジョブを実際のステータスのまま返します。すでに失敗したジョブは、その理由とともに失敗として返ります。それでも再実行したい場合は Idempotency-Bypass: true を送ってください。

アップロード

POST /api/py/v1/upload にはキーまたはログイン中のセッションが必要で、5 分間有効な署名付き POST フォームを返します。1 ファイルあたり最大 10 MB で、フォーム自体がこれを強制します。対応形式：.s1p .s2p .s3p .s4p .s6p .s8p .snp .csv .txt。アップロードしたオブジェクトは 24 時間保存されるので、それを使うジョブはその日のうちに投入してください。フォームの発行はアドレスごとに毎分 20 件までです。

結果

期限は 2 種類あります。resultExpiresAt は結果そのものが消える日時で、無料プランでは 30 日、Pro と API では無期限です。resultUrlExpiresIn は署名付きの resultUrl の有効期間で、15 分です。新しいリンクはもう一度ポーリングして取得し、URL はキャッシュしないでください。結果が消えた後もステータスは completed のままで、種類は result_expired になり、URL はありません。

パラメーターを省略する呼び出し元にとっての変更点

各ジョブタイプにはパラメーターの定義が 1 つだけあり、ハンドラー独自の代替値はなくなりました。すべてのフィールドを送っている場合、何も変わっていません。これらのいずれかを省略している場合、使われる値が以前と異なり、答えも変わります。

変更された既定値
jobType	パラメーター	変更前	変更後
`rf_cascade`	`nfSpec_db`	10 dB	6 dB
`rf_cascade`	`inputPower_dbm`	−60 dBm	−70 dBm
`rf_cascade`	`bandwidth_hz`	1 MHz	10 MHz
`rf_cascade`	`stages`	"[]"	必須（既定値なし）
`smps_control_loop`	`toleranceDistribution`	uniform	gaussian
`filter_monte_carlo`	`freqCutoff`	1 MHz	1 GHz
`impedance_match`	`freqStart`	1 MHz	800 MHz
`impedance_match`	`freqStop`	100 MHz	1.2 GHz
`antenna_sim`	`freq (instant solve)`	145 MHz	146 MHz
`pdn_impedance`	`portX_mm`	基板の中心（boardWidth_mm / 2）	3 分の 1 の点（boardWidth_mm / 3）
`pdn_impedance`	`portY_mm`	基板の中心（boardLength_mm / 2）	3 分の 1 の点（boardLength_mm / 3）

不明なパラメーターキーは、以前は破棄されて既定値で応答していました。現在は拒否され、拒否の内容にそのジョブタイプが受け付けるキーの一覧が示されます。

サンプリングを行うジョブタイプ（filter_monte_carlo やその他の最適化）では、乱数シードが投入したボディから導かれるため、同じ設計でもキーの組み合わせが違えば別のサンプルになります。パラメーターを省略することと既定値で送ることは、ソルバーにとっては同じリクエストですが、ボディは同じではありません。そのため、ウェブフォームからの実行とこの API からの実行は、サンプリング誤差の範囲で異なることがあります。実行を厳密に固定するには randomSeed を送ってください。

2026 年 9 月のリリースでの変更

既存の連携に影響する動作の変更です。すべてのパラメーターを送り、メッセージの文言ではなく errorKind を確認していれば、違いはこれらだけのはずです。それ以降の変更と各変更の告知日は API 変更履歴にあります。

変更内容

不明なパラメーターキーと範囲外の値は、破棄や制限をしてそのまま応答するのではなく、投入時に問題のパラメーターを示す 400 で拒否されます。
フィールドを省略する呼び出し元に対して、11 個のパラメーターの既定値が変わりました。上の表をご覧ください。
月間利用枠を使い切った場合は HTTP 402（errorKind は rate_limited）になり、Retry-After と resetAt が付きます。401 や単なる 429 にはなりません。これは API キーの月間利用枠と FDTD の解析モードの利用枠の両方に当てはまります。
アップロードには、ログイン中のセッションまたは API キーが必要になりました。匿名のリクエストは、何かが保存される前に 401 を受け取ります。匿名の無料実行環境では、ファイル入力を使う 2 つのツール（eye_diagram、sparam_pipeline）が完全に使えなくなります。どちらもアップロードしたファイルなしでは動かないためです。
API キーで投入したジョブは、そのキーの所有者のアカウントに属するようになりました。キー ID や投入元 IP だけでなく所有者によって認可され、所有者のダッシュボードのジョブ一覧に表示されます。
完了した結果には、計算値と並んで warnings と provenance（method、version、seed、実際に使われた正規化済みの入力）が付くようになりました。
すべての失敗（拒否された投入と、受理後に失敗したジョブ）に errorKind が付くようになりました。上の閉じた集合をご覧ください。
実行途中でワーカーが停止した（置き換えられた、またはタスクが停止された）ジョブは、止まったまま放置されるのではなく、種類 interrupted で失敗として扱われ、それに対する課金は解除されるようになりました。
結果は、その記録に示された期間だけ正確に保存されます。上の「結果」カードの resultExpiresAt をご覧ください。
インピーダンス合成の Auto トポロジーは、5 つのトポロジーすべてを比較し、最悪ケースのリターンロスが最もよいものを返すようになりました。以前は、クイックモードでも詳細設定の既定でも、常に L 型回路を構成していました。
インピーダンス合成は maxQ と componentSeries を反映するようになりました。以前はどちらも受け付けたうえで、黙って無視していました。
E 系列の標準値への丸めで、仮数がおよそ 9.55 を超える場合は、切り捨てではなく次のデケードの最初の値に切り上げるようになりました（9.9 nF → 10 nF）。同じ入力でも、インピーダンス整合の設計やフィルターのモンテカルロ実行で、部品の値が 1 つ変わることがあります。
インピーダンスのページからエクスポートした SPICE ネットリストには、理想値ではなく標準値（丸めた値）の部品が入り、系列名を示すヘッダー行が付くようになりました。
パワーインダクターと結合インダクターの設計は、ほかの入力から導くのではなく、指定したインダクタンスとピーク電流から寸法を決めるようになりました。フライバック変圧器とフォワード変圧器は変わりません。指定したピーク電流が指定したインダクタンスのリップルと矛盾するリクエストには、ripple_exceeds_peak の警告が付きます。
デプロイに関する注記：このロールアウトでは API のバリデーターがワーカーより先にデプロイされたため、その間にキューに入ったジョブのうち、ボディにスペルミスのあるキー（以前は既定値で黙って受け付けていたもの）を含むものは、最後まで実行されずに投入時に拒否されました。

投入

curl -X POST https://rftools.io/api/py/v1/jobs \
  -H "X-API-Key: $RFTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

job = client.submit_job("sat_link_budget", {"latitude_deg": 40.7, "longitude_deg": -74, "frequency_ghz": 12})
job = job.wait(timeout=600)
print(job.status, job.result())

const response = await fetch("https://rftools.io/api/py/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "sat_link_budget",
    "params": {
      "latitude_deg": 40.7,
      "longitude_deg": -74,
      "frequency_ghz": 12
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "jobType": "sat_link_budget",
	  "params": {
	    "latitude_deg": 40.7,
	    "longitude_deg": -74,
	    "frequency_ghz": 12
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

application/json

{
  "jobId": "6f1c2d4e-…",
  "status": "queued",
  "queuePosition": 1,
  "queueTotal": 1
}

キューに入りました。jobId をポーリングしてください。

{
  "errorKind": "invalid_request",
  "detail": [
    {
      "param": "frequency_ghz",
      "value": 900,
      "reason": "Frequency (frequency_ghz) must be between 0.1 and 100 GHz (got 900 GHz).",
      "allowed": "0.1 to 100 GHz"
    },
    {
      "param": "longitude_deg",
      "value": null,
      "reason": "Site Longitude (longitude_deg) is required.",
      "allowed": null
    }
  ]
}

契約外のパラメーターすべてを一度に示します。キューには入っていません。

{
  "detail": "You already have 3 jobs queued or running, and the limit is 3. Wait for one to finish.",
  "pending": 3,
  "limit": 3,
  "errorKind": "rate_limited"
}

同時に実行中のジョブが多すぎます。Retry-After 付き。

ポーリング

curl https://rftools.io/api/py/v1/jobs/JOB_ID \
  -H "X-API-Key: $RFTOOLS_API_KEY"

import os

import httpx

response = httpx.get(
    "https://rftools.io/api/py/v1/jobs/JOB_ID",
    headers={"X-API-Key": os.environ["RFTOOLS_API_KEY"]},
)
print(response.status_code, response.json())

const response = await fetch("https://rftools.io/api/py/v1/jobs/JOB_ID", {
  headers: {
    "X-API-Key": process.env.RFTOOLS_API_KEY,
  },
});
console.log(response.status, await response.json());

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://rftools.io/api/py/v1/jobs/JOB_ID", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("X-API-Key", os.Getenv("RFTOOLS_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

投入せずに見積もる

curl -X POST https://rftools.io/api/py/v1/jobs/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }'

import rftools

client = rftools.Client()  # reads RFTOOLS_API_KEY, or the key `rftools login` saved

est = client.estimate_job("fdtd_sparam", {"traceW": 0.42, "subH": 0.51, "solveMode": "express"})
print(est.lane, est.wall_seconds, est.within_budget)

const response = await fetch("https://rftools.io/api/py/v1/jobs/estimate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jobType": "fdtd_sparam",
    "params": {
      "traceW": 0.42,
      "subH": 0.51,
      "solveMode": "express"
    }
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{
	  "jobType": "fdtd_sparam",
	  "params": {
	    "traceW": 0.42,
	    "subH": 0.51,
	    "solveMode": "express"
	  }
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/jobs/estimate", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}