Documentation
Docs
Send numbers over HTTP, get tested answers back. Everything you need is on this page.
- Request a key. During the private preview you can use the demo key below on your own machine.
- Start the local server with
node server.js. It listens onhttp://localhost:5900. - Send your first request:
curl http://localhost:5900/v1/stats/describe \
-H "Authorization: Bearer coops_test_growth_Zp5hB8cJ2sY6dF1q" \
-H "Content-Type: application/json" \
-d '{"data": [12, 15, 9, 22, 18, 30]}'
You get back JSON with the mean, spread and percentiles. Every other endpoint works the same way: numbers in, numbers out.
Authentication
Every request carries your key in a header. Keys are secret, so keep them on your server and never in a web page or a mobile app.
Authorization: Bearer YOUR_KEY
The base URL will be https://api.moluscca.com. Today, in the private preview, it is http://localhost:5900. Everything is HTTPS and JSON. Bodies can be up to 1 MB.
Two endpoints need no key: GET /v1/health and GET /v1/climate/coverage.
Errors
Errors use normal HTTP status codes and always have the same shape, so you can handle them in one place.
{
"error": {
"type": "invalid_request",
"code": "invalid_input",
"message": "returns[1] is not a valid return. Use decimals above -1, so 1.2% is 0.012.",
"request_id": "req_3f9a1c2b7d10",
"param": "returns[1]"
}
}
| Status | Code | What happened |
|---|---|---|
| 400 | invalid_input | A field is missing or has the wrong shape. The message says which, and param names the field. |
| 400 | invalid_json | The body is not valid JSON, or is not an object. |
| 401 | missing_api_key | No Authorization header. |
| 401 | invalid_api_key | The key is wrong or revoked. |
| 403 | plan_required | Your plan does not include this endpoint, for example climate data on Free or Starter. |
| 404 | not_found | No endpoint at that path. |
| 404 | location_not_covered | Climate data has nothing within 50 km of the point. |
| 405 | method_not_allowed | Use POST for maths and GET for data. |
| 413 | request_too_large | The body is over 1 MB. |
| 429 | monthly_limit_reached | You have used this month's credits. |
| 500 | server_error | Our fault. Retry, and quote the request id if it keeps happening. |
Every response has an X-Request-Id header. Include it when you write to us.
Rate limits and credits
Each plan comes with a monthly number of credits. Most requests cost 1 credit. Big simulations cost more, and we tell you the cost up front: a Monte Carlo run with more than 10,000 paths costs 10 credits. Requests that fail with an error cost nothing.
| Plan | Credits a month | Climate data |
|---|---|---|
| Free | 1,000 | No |
| Starter | 25,000 | No |
| Growth | 150,000 | Yes |
| Scale | 750,000 | Yes |
Every response tells you where you stand:
X-RateLimit-Limit: 150000 X-RateLimit-Remaining: 149212 X-Call-Cost: 1
When the credits run out you get a 429 with the date they reset. Check your balance any time with GET /v1/usage.
API reference
Each endpoint below shows a real request and the real response from the server. Numbers are rounded to 10 significant figures. Press Try it live to run it against your local server.
Statistics
Describe a column
/v1/stats/describeSummarises a list of numbers: average, spread, skew, tails and the usual percentiles.
| Parameter | Type | Required | What it is |
|---|---|---|---|
data | number[] | yes* | The values. At least 2. |
columns | object | no | Instead of data, named lists such as { "claims": [...], "premium": [...] }. Up to 50. |
Starred fields: send one of them.
curl https://api.moluscca.com/v1/stats/describe \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": [12, 15, 9, 22, 18, 30, 11, 14]
}'const res = await fetch("https://api.moluscca.com/v1/stats/describe", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"data": [12, 15, 9, 22, 18, 30, 11, 14]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/stats/describe",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"data": [12, 15, 9, 22, 18, 30, 11, 14]
},
)
print(res.json())Response
{
"object": "describe",
"n": 8,
"sum": 131,
"mean": 16.375,
"sd": 6.864765109,
"variance": 47.125,
"min": 9,
"max": 30,
"skewness": 1.210248436,
"excess_kurtosis": 1.22380413,
"cv": 0.4192222967,
"quantiles": { "p1": 9.14, "p5": 9.7, "p25": 11.75, "p50": 14.5, "p75": 19, "p95": 27.2, "p99": 29.44 }
}
Regression
/v1/stats/regressionFits a straight-line model (OLS) or a Poisson or logistic GLM, with standard errors and p-values.
| Parameter | Type | Required | What it is |
|---|---|---|---|
y | number[] | yes | The outcome. |
x | number[] | number[][] | object | yes | One column, a list of rows, or named columns. |
family | string | no | "gaussian" (default, OLS), "poisson" for counts, "binomial" for 0 or 1 outcomes. |
intercept | boolean | no | Add an intercept. Default true. |
curl https://api.moluscca.com/v1/stats/regression \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{ "x": [1, 2, 3, 4, 5], "y": [2, 4, 5, 4, 5] }'const res = await fetch("https://api.moluscca.com/v1/stats/regression", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ "x": [1, 2, 3, 4, 5], "y": [2, 4, 5, 4, 5] })
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/stats/regression",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={ "x": [1, 2, 3, 4, 5], "y": [2, 4, 5, 4, 5] },
)
print(res.json())Response
{
"object": "regression",
"family": "gaussian",
"method": "ordinary least squares",
"n": 5,
"df_residual": 3,
"coefficients": [
{
"term": "intercept",
"estimate": 2.2,
"std_error": 0.938083152,
"t_value": 2.34520788,
"p_value": 0.100743
},
{
"term": "x",
"estimate": 0.6,
"std_error": 0.2828427125,
"t_value": 2.121320344,
"p_value": 0.124027
}
],
"r_squared": 0.6,
"adj_r_squared": 0.4666666667,
"residual_se": 0.894427191,
"f_statistic": 4.5,
"f_p_value": 0.124027,
"rss": 2.4
}
Risk measures
Value at risk and TVaR
/v1/risk/varTells you how much you could lose on a bad day, three ways: from history, from a normal curve, and with a skew correction.
| Parameter | Type | Required | What it is |
|---|---|---|---|
returns | number[] | yes* | Periodic returns as decimals, so 1.2% is 0.012. At least 5. |
losses | number[] | yes* | Instead of returns, losses as positive amounts. |
value | number | no | Portfolio value used to turn returns into money. Default 1. |
confidence | number | number[] | no | Default [0.95, 0.99]. |
horizon | integer | no | Days. Scaled by the square root of time. Default 1. |
Starred fields: send one of them.
curl https://api.moluscca.com/v1/risk/var \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177],
"value": 250000,
"confidence": 0.99
}'const res = await fetch("https://api.moluscca.com/v1/risk/var", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177],
"value": 250000,
"confidence": 0.99
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/risk/var",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177],
"value": 250000,
"confidence": 0.99
},
)
print(res.json())Response
{
"object": "risk_var",
"input": "returns",
"observations": 12,
"horizon": 1,
"scaling": "none",
"loss_mean": 381.25,
"loss_sd": 2616.254371,
"skewness": 0.9184811324,
"excess_kurtosis": -0.3594897596,
"levels": [
{
"confidence": 0.99,
"historical": { "var": 5270.5, "tvar": 5375, "tail_observations": 1 },
"normal": { "var": 6467.567793, "tvar": 7354.128353 },
"cornish_fisher": { "var": 7184.023713 }
}
],
"notes": ["Losses are positive numbers. Historical VaR uses the type 7 quantile (Excel PERCENTILE.INC). TVaR is the mean of losses at or above VaR."]
}
Portfolio risk
/v1/risk/portfolioTakes positions and prices (or one return series) and returns VaR, drawdown, Sharpe, beta, each position's share of risk and stress tests.
| Parameter | Type | Required | What it is |
|---|---|---|---|
returns | number[] | yes* | Simple mode: one series of returns. |
dates, benchmark, positions | arrays | yes* | Full mode: dates, a benchmark { name, prices } and positions [{ symbol, sector, quantity, prices }]. |
value | number | no | Simple mode portfolio value. Default 1,000,000. |
options | object | no | confidence, horizon_days, window_days, forecast_days. |
Starred fields: send one of them.
curl https://api.moluscca.com/v1/risk/portfolio \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Demo fund",
"currency": "USD",
"value": 250000,
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177, 0.0059, 0.0021, -0.0033, 0.0075, -0.0092, 0.0018, 0.0063, -0.0041],
"options": { "confidence": 0.95, "horizon_days": 1, "forecast_days": 3 }
}'const res = await fetch("https://api.moluscca.com/v1/risk/portfolio", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "Demo fund",
"currency": "USD",
"value": 250000,
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177, 0.0059, 0.0021, -0.0033, 0.0075, -0.0092, 0.0018, 0.0063, -0.0041],
"options": { "confidence": 0.95, "horizon_days": 1, "forecast_days": 3 }
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/risk/portfolio",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"name": "Demo fund",
"currency": "USD",
"value": 250000,
"returns": [0.0041, -0.0123, 0.0067, 0.0012, -0.0215, 0.0089, 0.0034, -0.0051, 0.0102, -0.0008, 0.0046, -0.0177, 0.0059, 0.0021, -0.0033, 0.0075, -0.0092, 0.0018, 0.0063, -0.0041],
"options": { "confidence": 0.95, "horizon_days": 1, "forecast_days": 3 }
},
)
print(res.json())Response
{
"object": "portfolio_risk",
"as_of": null,
"currency": "USD",
"confidence": 0.95,
"horizon_days": 1,
"observations": 20,
"value": 250000,
"var_historical": 4472.5,
"expected_shortfall": 5375,
"var_parametric": 3766.79,
"volatility_annual": 0.139961,
"return_annual": -0.14238,
"period_return": -0.011975,
"sharpe": -1.017287,
"sortino": -1.228632,
"max_drawdown": -0.025893,
"worst_day": -0.0215,
"forecast": [
{ "day": 1, "p10": 247028.47, "p50": 249849.46, "p90": 252702.67 },
{ "day": 2, "p10": 245721.27, "p50": 249699.01, "p90": 253741.14 },
{ "day": 3, "p10": 244688.62, "p50": 249548.65, "p90": 254505.22 }
],
"warnings": ["Simple mode: beta, alpha and stress tests need positions and a benchmark, so they are not returned."]
}
Distributions and tails
Fit distributions
/v1/distributions/fitTries several distributions on your data and ranks them, so you can see which shape fits best and by how much.
| Parameter | Type | Required | What it is |
|---|---|---|---|
data | number[] | yes | At least 5 values. Positive-only distributions are skipped if any value is 0 or less. |
distributions | string[] | no | Any of normal, lognormal, exponential, gamma, weibull, pareto. Default all. |
curl https://api.moluscca.com/v1/distributions/fit \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": [1200, 3400, 900, 15000, 2600, 4100, 800, 7600, 2200, 1900, 31000, 5200],
"distributions": ["lognormal", "gamma", "weibull", "exponential"]
}'const res = await fetch("https://api.moluscca.com/v1/distributions/fit", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"data": [1200, 3400, 900, 15000, 2600, 4100, 800, 7600, 2200, 1900, 31000, 5200],
"distributions": ["lognormal", "gamma", "weibull", "exponential"]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/distributions/fit",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"data": [1200, 3400, 900, 15000, 2600, 4100, 800, 7600, 2200, 1900, 31000, 5200],
"distributions": ["lognormal", "gamma", "weibull", "exponential"]
},
)
print(res.json())Response
{
"object": "distribution_fit",
"observations": 12,
"method": "maximum likelihood",
"ranked_by": "aic",
"best": "lognormal",
"fits": [
{
"distribution": "lognormal",
"params": { "mu": 8.132192518, "sigma": 1.060487116 },
"log_likelihood": -115.3183128,
"aic": 234.6366255,
"bic": 235.6064388,
"ks_statistic": 0.1000926968,
"mean": 5970.040438,
"quantiles": { "p50": 3402.250889, "p90": 13243.49069, "p99": 40104.92672, "p995": 52251.62702 },
"delta_aic": 0
},
{
"distribution": "exponential",
"params": { "rate": 0.0001581027668 },
"log_likelihood": -117.0271838,
"aic": 236.0543675,
"bic": 236.5392742,
"ks_statistic": 0.1896418096,
"mean": 6325,
"quantiles": { "p50": 4384.155917, "p90": 14563.85071, "p99": 29127.70143, "p995": 33511.85734 },
"delta_aic": 1.417742
},
{
"distribution": "weibull",
"params": { "shape": 0.8960047465, "scale": 5930.901885 },
"log_likelihood": -116.879363,
"aic": 237.7587259,
"bic": 238.7285392,
"ks_statistic": 0.1611332721,
"mean": 6255.67636,
"quantiles": { "p50": 3939.775957, "p90": 15044.47993, "p99": 32609.66796, "p995": 38133.45501 },
"delta_aic": 3.1221004
},
{
"distribution": "gamma",
"params": { "shape": 0.9380248455, "scale": 6742.891759 },
"log_likelihood": -117.0108771,
"aic": 238.0217542,
"bic": 238.9915675,
"ks_statistic": 0.1827728799,
"mean": 6325,
"quantiles": null,
"delta_aic": 3.3851287
}
],
"skipped": [],
"notes": ["Pareto is Type I with xmin set to the smallest value. Gamma quantiles are not returned yet."]
}
Extreme values
/v1/extreme/evtModels only the worst outcomes (a generalised Pareto tail) to estimate 1-in-100 or 1-in-200 events.
| Parameter | Type | Required | What it is |
|---|---|---|---|
data | number[] | yes | At least 20 values, with at least 10 above the threshold. |
threshold | number | no | Where the tail starts. |
threshold_quantile | number | no | Or pick the threshold as a percentile. Default 0.9. |
return_periods | number[] | no | Default [10, 50, 100, 200]. |
observations_per_year | number | no | Turns return periods into years. |
confidence | number[] | no | Tail VaR and ES levels. Default [0.99, 0.995]. |
curl https://api.moluscca.com/v1/extreme/evt \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": [1500, 2600, 3500, 4300, 5100, 5900, 6800, 7600, 8500, 9300, 10300, 11200, 12300, 13300, 14400, 15600, 16900, 18200, 19700, 21200, 22900, 24700, 26600, 28700, 31000, 33600, 36400, 39600, 43200, 47200, 51900, 57400, 63900, 71800, 81600, 94500, 112100, 138800, 186600, 324400],
"threshold_quantile": 0.7,
"observations_per_year": 20,
"return_periods": [10, 100, 200]
}'const res = await fetch("https://api.moluscca.com/v1/extreme/evt", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"data": [1500, 2600, 3500, 4300, 5100, 5900, 6800, 7600, 8500, 9300, 10300, 11200, 12300, 13300, 14400, 15600, 16900, 18200, 19700, 21200, 22900, 24700, 26600, 28700, 31000, 33600, 36400, 39600, 43200, 47200, 51900, 57400, 63900, 71800, 81600, 94500, 112100, 138800, 186600, 324400],
"threshold_quantile": 0.7,
"observations_per_year": 20,
"return_periods": [10, 100, 200]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/extreme/evt",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"data": [1500, 2600, 3500, 4300, 5100, 5900, 6800, 7600, 8500, 9300, 10300, 11200, 12300, 13300, 14400, 15600, 16900, 18200, 19700, 21200, 22900, 24700, 26600, 28700, 31000, 33600, 36400, 39600, 43200, 47200, 51900, 57400, 63900, 71800, 81600, 94500, 112100, 138800, 186600, 324400],
"threshold_quantile": 0.7,
"observations_per_year": 20,
"return_periods": [10, 100, 200]
},
)
print(res.json())Response
{
"object": "evt_gpd",
"method": "peaks over threshold, generalised Pareto fitted by maximum likelihood",
"observations": 40,
"threshold": 40680,
"exceedances": 12,
"exceedance_rate": 0.3,
"shape_xi": 0.2522274176,
"scale_sigma": 49764.00773,
"log_likelihood": -144.8072742,
"return_levels": [
{ "period": 10, "unit": "years", "level": 397524.4504 },
{ "period": 100, "unit": "years", "level": 833869.2668 },
{ "period": 200, "unit": "years", "level": 1023096.527 }
],
"tail": [
{ "confidence": 0.99, "var": 308639.4939, "es": 465573.2217 },
{ "confidence": 0.995, "var": 397524.4504, "es": 584439.5168 }
],
"warnings": ["Fewer than 30 values above the threshold: estimates are rough."]
}
Simulation
Monte Carlo simulation
/v1/simulate/montecarloSimulates thousands of possible futures for a price or a rate and returns the spread of outcomes. Same seed, same answer.
| Parameter | Type | Required | What it is |
|---|---|---|---|
model | string | yes | "gbm" (prices), "ou" (rates that pull back to a level) or "merton" (prices with jumps). |
params | object | yes | gbm: s0, mu, sigma. ou: x0, kappa, theta, sigma. merton: s0, mu, sigma, jump_rate, jump_mean, jump_sd. |
horizon | number | no | Years. Default 1. |
steps | integer | no | Default 252. |
paths | integer | no | 10 to 100,000. Default 10,000. Over 10,000 costs 10 credits. |
seed | integer | no | Default 42. |
sample_paths | integer | no | Paths to return in full, 0 to 10. Default 3. |
curl https://api.moluscca.com/v1/simulate/montecarlo \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gbm",
"params": { "s0": 100, "mu": 0.06, "sigma": 0.2 },
"horizon": 1,
"steps": 4,
"paths": 5000,
"seed": 7,
"sample_paths": 0
}'const res = await fetch("https://api.moluscca.com/v1/simulate/montecarlo", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"model": "gbm",
"params": { "s0": 100, "mu": 0.06, "sigma": 0.2 },
"horizon": 1,
"steps": 4,
"paths": 5000,
"seed": 7,
"sample_paths": 0
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/simulate/montecarlo",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"model": "gbm",
"params": { "s0": 100, "mu": 0.06, "sigma": 0.2 },
"horizon": 1,
"steps": 4,
"paths": 5000,
"seed": 7,
"sample_paths": 0
},
)
print(res.json())Response
{
"object": "monte_carlo",
"model": "gbm",
"seed": 7,
"paths": 5000,
"steps": 4,
"horizon": 1,
"dt": 0.25,
"terminal": {
"mean": 105.7183716,
"sd": 21.7373373,
"min": 47.25331142,
"max": 216.9763258,
"p1": 64.93733757,
"p5": 74.56899992,
"p50": 103.1562102,
"p95": 144.9727786,
"p99": 165.6957699,
"standard_error_of_mean": 0.3074123721
},
"theory": { "mean": 106.1836547, "sd": 21.45087863 },
"fan": [
{ "t": 0.25, "p5": 85.489866, "p50": 100.86064, "p95": 118.76846, "mean": 101.28763 },
{ "t": 0.5, "p5": 80.696746, "p50": 101.94641, "p95": 128.76602, "mean": 102.87485 },
{ "t": 0.75, "p5": 77.053392, "p50": 102.57541, "p95": 136.89283, "mean": 104.11728 },
{ "t": 1, "p5": 74.569, "p50": 103.15621, "p95": 144.97278, "mean": 105.71837 }
],
"sample_paths": [],
"billing": { "calls_counted": 1 }
}
Markov chains
/v1/stochastic/markovWorks out where things end up when they move between states, like loans moving from current to late to default.
| Parameter | Type | Required | What it is |
|---|---|---|---|
matrix | number[][] | yes | Square, each row adds up to 1. |
states | string[] | no | Names for the states. |
steps | integer | no | Default 1. |
initial | number[] | no | Starting mix, adds up to 1. |
curl https://api.moluscca.com/v1/stochastic/markov \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"states": ["Current", "Late", "Default"],
"matrix": [
[0.92, 0.07, 0.01],
[0.35, 0.55, 0.1],
[0, 0, 1]
],
"steps": 12,
"initial": [1, 0, 0]
}'const res = await fetch("https://api.moluscca.com/v1/stochastic/markov", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"states": ["Current", "Late", "Default"],
"matrix": [
[0.92, 0.07, 0.01],
[0.35, 0.55, 0.1],
[0, 0, 1]
],
"steps": 12,
"initial": [1, 0, 0]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/stochastic/markov",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"states": ["Current", "Late", "Default"],
"matrix": [
[0.92, 0.07, 0.01],
[0.35, 0.55, 0.1],
[0, 0, 1]
],
"steps": 12,
"initial": [1, 0, 0]
},
)
print(res.json())Response
{
"object": "markov_chain",
"states": ["Current", "Late", "Default"],
"steps": 12,
"n_step_matrix": [
[0.6696496754, 0.1096597449, 0.2206905797],
[0.5482987247, 0.09001959502, 0.3616816803],
[0, 0, 1]
],
"distribution_after_steps": [0.6696496754, 0.1096597449, 0.2206905797],
"absorbing_states": ["Default"],
"expected_steps_to_absorption": { "Current": 45.2173913, "Late": 37.39130435 },
"absorption_probabilities": {
"Current": { "Default": 1 },
"Late": { "Default": 1 }
}
}
Insurance and reserving
Chain ladder with Mack
/v1/reserving/chain-ladderEstimates how much more an insurer will pay on claims already reported, and how uncertain that figure is.
| Parameter | Type | Required | What it is |
|---|---|---|---|
triangle | number[][] | yes | Run-off triangle, oldest year first. Row i has one fewer value than the row above. |
cumulative | boolean | no | false if you send incremental amounts. Default true. |
origins | string[] | no | Labels such as years. |
sigma_method | string | no | "mack" (default) or "log-linear" for the last variance. |
include_triangle | boolean | no | Return the completed triangle. |
curl https://api.moluscca.com/v1/reserving/chain-ladder \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"triangle": [
[5012, 8269, 10907, 11805, 13539, 16181, 18009, 18608, 18662, 18834],
[106, 4285, 5396, 10666, 13782, 15599, 15496, 16169, 16704],
[3410, 8992, 13873, 16141, 18735, 22214, 22863, 23466],
[5655, 11555, 15766, 21266, 23425, 26083, 27067],
[1092, 9565, 15836, 22169, 25955, 26180],
[1513, 6445, 11702, 12935, 15852],
[557, 4020, 10946, 12314],
[1351, 6947, 13112],
[3133, 5395],
[2063]
],
"origins": ["1981", "1982", "1983", "1984", "1985", "1986", "1987", "1988", "1989", "1990"]
}'const res = await fetch("https://api.moluscca.com/v1/reserving/chain-ladder", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"triangle": [
[5012, 8269, 10907, 11805, 13539, 16181, 18009, 18608, 18662, 18834],
[106, 4285, 5396, 10666, 13782, 15599, 15496, 16169, 16704],
[3410, 8992, 13873, 16141, 18735, 22214, 22863, 23466],
[5655, 11555, 15766, 21266, 23425, 26083, 27067],
[1092, 9565, 15836, 22169, 25955, 26180],
[1513, 6445, 11702, 12935, 15852],
[557, 4020, 10946, 12314],
[1351, 6947, 13112],
[3133, 5395],
[2063]
],
"origins": ["1981", "1982", "1983", "1984", "1985", "1986", "1987", "1988", "1989", "1990"]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/reserving/chain-ladder",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"triangle": [
[5012, 8269, 10907, 11805, 13539, 16181, 18009, 18608, 18662, 18834],
[106, 4285, 5396, 10666, 13782, 15599, 15496, 16169, 16704],
[3410, 8992, 13873, 16141, 18735, 22214, 22863, 23466],
[5655, 11555, 15766, 21266, 23425, 26083, 27067],
[1092, 9565, 15836, 22169, 25955, 26180],
[1513, 6445, 11702, 12935, 15852],
[557, 4020, 10946, 12314],
[1351, 6947, 13112],
[3133, 5395],
[2063]
],
"origins": ["1981", "1982", "1983", "1984", "1985", "1986", "1987", "1988", "1989", "1990"]
},
)
print(res.json())Response
{
"object": "chain_ladder",
"method": "volume-weighted chain ladder with Mack (1993) standard errors",
"sigma_method": "mack",
"development_factors": [2.999358651, 1.623522754, 1.270888115, 1.171674633, 1.113384886, 1.041934638, 1.033263554, 1.016936481, 1.00921659],
"cumulative_factors": [8.920233897, 2.974047099, 1.831848117, 1.441392122, 1.230198283, 1.104917355, 1.060447858, 1.026309167, 1.00921659],
"sigma_squared": [27883.47939, 1108.526286, 691.4427846, 61.22999539, 119.439054, 40.81986269, 1.343425466, 7.883203715, 1.343425466],
"origins": [
{ "origin": "1981", "latest": 18834, "ultimate": 18834, "reserve": 0, "mack_se": 0, "cv": null },
{
"origin": "1982",
"latest": 16704,
"ultimate": 16857.95392,
"reserve": 153.9539171,
"mack_se": 206.2200594,
"cv": 1.339492124
},
{
"origin": "1983",
"latest": 23466,
"ultimate": 24083.37092,
"reserve": 617.3709238,
"mack_se": 623.3766726,
"cv": 1.009727942
},
{
"origin": "1984",
"latest": 27067,
"ultimate": 28703.14216,
"reserve": 1636.142163,
"mack_se": 747.1752251,
"cv": 0.4566688897
},
{
"origin": "1985",
"latest": 26180,
"ultimate": 28926.73634,
"reserve": 2746.736343,
"mack_se": 1469.45715,
"cv": 0.5349829637
},
{
"origin": "1986",
"latest": 15852,
"ultimate": 19501.10318,
"reserve": 3649.103184,
"mack_se": 2001.856931,
"cv": 0.5485887436
},
{
"origin": "1987",
"latest": 12314,
"ultimate": 17749.30259,
"reserve": 5435.30259,
"mack_se": 2209.242094,
"cv": 0.4064616564
},
{
"origin": "1988",
"latest": 13112,
"ultimate": 24019.19251,
"reserve": 10907.19251,
"mack_se": 5357.869298,
"cv": 0.4912235017
},
{
"origin": "1989",
"latest": 5395,
"ultimate": 16044.9841,
"reserve": 10649.9841,
"mack_se": 6333.165866,
"cv": 0.5946643493
},
{
"origin": "1990",
"latest": 2063,
"ultimate": 18402.44253,
"reserve": 16339.44253,
"mack_se": 24566.28791,
"cv": 1.503496087
}
],
"totals": {
"latest": 160987,
"ultimate": 213122.2283,
"reserve": 52135.22826,
"mack_se": 26909.01116,
"cv": 0.5161387425
},
"notes": ["No tail factor is applied: the oldest origin year is treated as fully developed."]
}
This is the RAA triangle from Mack (1993). The result matches the published reserve of 52,135 and standard error of 26,909.
Aggregate loss
/v1/aggregate/lossCombines how often claims happen with how big they are, to give the full spread of a year's total losses and layer costs.
| Parameter | Type | Required | What it is |
|---|---|---|---|
frequency | object | yes | { distribution: "poisson", lambda } or "negative_binomial" with r, beta, or "binomial" with n, p. |
severity | object | yes | { distribution: lognormal | gamma | exponential | pareto, params, step } or { pmf, step }. |
max_points | integer | no | Grid size, 100 to 10,000. Default 4,000. |
layers | object[] | no | Up to 10 of { attachment, limit } to price. |
confidence | number[] | no | Default [0.9, 0.95, 0.99, 0.995]. |
curl https://api.moluscca.com/v1/aggregate/loss \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"frequency": { "distribution": "poisson", "lambda": 3 },
"severity": {
"distribution": "lognormal",
"params": { "mu": 9, "sigma": 1.1 },
"step": 1000
},
"max_points": 600,
"layers": [
{ "attachment": 50000, "limit": 100000 }
],
"confidence": [0.95, 0.995]
}'const res = await fetch("https://api.moluscca.com/v1/aggregate/loss", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"frequency": { "distribution": "poisson", "lambda": 3 },
"severity": {
"distribution": "lognormal",
"params": { "mu": 9, "sigma": 1.1 },
"step": 1000
},
"max_points": 600,
"layers": [
{ "attachment": 50000, "limit": 100000 }
],
"confidence": [0.95, 0.995]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/aggregate/loss",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"frequency": { "distribution": "poisson", "lambda": 3 },
"severity": {
"distribution": "lognormal",
"params": { "mu": 9, "sigma": 1.1 },
"step": 1000
},
"max_points": 600,
"layers": [
{ "attachment": 50000, "limit": 100000 }
],
"confidence": [0.95, 0.995]
},
)
print(res.json())Response
{
"object": "aggregate_loss",
"method": "Panjer recursion, (a, b, 0) frequency",
"discretisation": "rounding (mass at k x step from the interval around it)",
"step": 1000,
"points": 600,
"probability_captured": 0.99980184,
"frequency_mean": 3,
"frequency_variance": 3,
"severity_mean": 14838.79034,
"mean": 44362.74363,
"sd": 45793.92842,
"prob_zero": 0.050640868,
"quantiles": [
{ "confidence": 0.95, "var": 130000, "tvar": 184914.6597 },
{ "confidence": 0.995, "var": 264000, "tvar": 337360.6092 }
],
"layers": [
{ "attachment": 50000, "limit": 100000, "expected_loss": 12092.7931 }
],
"cdf": [
{ "x": 0, "cdf": 0.050640868 },
{ "x": 6000, "cdf": 0.13218458 },
{ "x": 12000, "cdf": 0.22722969 },
{ "x": 18000, "cdf": 0.32024571 },
{ "x": 24000, "cdf": 0.40694307 },
{ "x": 30000, "cdf": 0.48538859 },
{ "x": 36000, "cdf": 0.55501446 },
{ "x": 42000, "cdf": 0.61601887 },
{ "x": 48000, "cdf": 0.6690005 },
{ "x": 54000, "cdf": 0.71473895 },
{ "x": 60000, "cdf": 0.75406614 },
{ "x": 66000, "cdf": 0.78779404 },
{ "x": 72000, "cdf": 0.81667681 },
{ "x": 78000, "cdf": 0.84139394 },
{ "x": 84000, "cdf": 0.86254535 },
{ "x": 90000, "cdf": 0.88065358 },
{ "x": 96000, "cdf": 0.89616937 },
{ "x": 102000, "cdf": 0.90947892 },
{ "x": 108000, "cdf": 0.92091161 },
{ "x": 114000, "cdf": 0.9307474 },
{ "x": 120000, "cdf": 0.93922378 },
{ "x": 126000, "cdf": 0.94654193 },
{ "x": 132000, "cdf": 0.95287218 },
{ "x": 138000, "cdf": 0.95835869 },
{ "x": 144000, "cdf": 0.96312356 },
{ "x": 150000, "cdf": 0.96727022 },
{ "x": 156000, "cdf": 0.97088639 },
{ "x": 162000, "cdf": 0.97404654 },
{ "x": 168000, "cdf": 0.97681396 },
{ "x": 174000, "cdf": 0.97924253 },
{ "x": 180000, "cdf": 0.98137817 },
{ "x": 186000, "cdf": 0.98326011 },
{ "x": 192000, "cdf": 0.98492188 },
{ "x": 198000, "cdf": 0.9863922 },
{ "x": 204000, "cdf": 0.98769574 },
{ "x": 210000, "cdf": 0.9888537 },
{ "x": 216000, "cdf": 0.98988432 },
{ "x": 222000, "cdf": 0.99080338 },
{ "x": 228000, "cdf": 0.99162447 },
{ "x": 234000, "cdf": 0.9923594 },
{ "x": 240000, "cdf": 0.99301839 },
{ "x": 246000, "cdf": 0.99361035 },
{ "x": 252000, "cdf": 0.99414301 },
{ "x": 258000, "cdf": 0.99462312 },
{ "x": 264000, "cdf": 0.99505661 },
{ "x": 270000, "cdf": 0.99544862 },
{ "x": 276000, "cdf": 0.9958037 },
{ "x": 282000, "cdf": 0.99612582 },
{ "x": 288000, "cdf": 0.99641849 },
{ "x": 294000, "cdf": 0.99668479 },
{ "x": 300000, "cdf": 0.99692746 },
{ "x": 306000, "cdf": 0.99714891 },
{ "x": 312000, "cdf": 0.99735127 },
{ "x": 318000, "cdf": 0.99753644 },
{ "x": 324000, "cdf": 0.9977061 },
{ "x": 330000, "cdf": 0.99786176 },
{ "x": 336000, "cdf": 0.99800474 },
{ "x": 342000, "cdf": 0.99813625 },
{ "x": 348000, "cdf": 0.99825734 },
{ "x": 354000, "cdf": 0.99836898 },
{ "x": 360000, "cdf": 0.99847202 },
{ "x": 366000, "cdf": 0.99856723 },
{ "x": 372000, "cdf": 0.99865529 },
{ "x": 378000, "cdf": 0.99873684 },
{ "x": 384000, "cdf": 0.99881244 },
{ "x": 390000, "cdf": 0.99888258 },
{ "x": 396000, "cdf": 0.99894772 },
{ "x": 402000, "cdf": 0.99900829 },
{ "x": 408000, "cdf": 0.99906466 },
{ "x": 414000, "cdf": 0.99911716 },
{ "x": 420000, "cdf": 0.9991661 },
{ "x": 426000, "cdf": 0.99921177 },
{ "x": 432000, "cdf": 0.99925442 },
{ "x": 438000, "cdf": 0.99929429 },
{ "x": 444000, "cdf": 0.99933158 },
{ "x": 450000, "cdf": 0.99936649 },
{ "x": 456000, "cdf": 0.9993992 },
{ "x": 462000, "cdf": 0.99942988 },
{ "x": 468000, "cdf": 0.99945866 },
{ "x": 474000, "cdf": 0.99948569 },
{ "x": 480000, "cdf": 0.99951108 },
{ "x": 486000, "cdf": 0.99953497 },
{ "x": 492000, "cdf": 0.99955744 },
{ "x": 498000, "cdf": 0.9995786 },
{ "x": 504000, "cdf": 0.99959854 },
{ "x": 510000, "cdf": 0.99961735 },
{ "x": 516000, "cdf": 0.99963508 },
{ "x": 522000, "cdf": 0.99965183 },
{ "x": 528000, "cdf": 0.99966765 },
{ "x": 534000, "cdf": 0.9996826 },
{ "x": 540000, "cdf": 0.99969674 },
{ "x": 546000, "cdf": 0.99971012 },
{ "x": 552000, "cdf": 0.99972278 },
{ "x": 558000, "cdf": 0.99973478 },
{ "x": 564000, "cdf": 0.99974615 },
{ "x": 570000, "cdf": 0.99975694 },
{ "x": 576000, "cdf": 0.99976717 },
{ "x": 582000, "cdf": 0.99977688 },
{ "x": 588000, "cdf": 0.99978611 },
{ "x": 594000, "cdf": 0.99979487 }
],
"warnings": []
}
Broker loss ratio
/v1/insurance/loss-ratioReads a broker's book of policies and claims and returns loss ratios by line and client, with credibility and renewals.
| Parameter | Type | Required | What it is |
|---|---|---|---|
clients | object[] | yes | [{ id, name, renewal, policies: [{ line, premium }] }]. |
claims | object[] | no | [{ client, line, date, paid, outstanding }]. |
lines | object | no | { "Motor": { "commission": 0.15 } }. |
as_of | date | no | Defaults to the latest claim date. |
options | object | no | months, line, credibility_k, simulate. |
curl https://api.moluscca.com/v1/insurance/loss-ratio \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Demo book",
"currency": "INR",
"as_of": "2026-11-13",
"lines": {
"Motor": { "commission": 0.15 },
"Health": { "commission": 0.075 }
},
"clients": [
{
"id": "C001",
"name": "Kaveri Textiles",
"renewal": "2027-01-10",
"policies": [
{ "line": "Motor", "premium": 420000 },
{ "line": "Health", "premium": 1200000 }
]
},
{
"id": "C002",
"name": "Indus Logistics",
"renewal": "2026-12-02",
"policies": [
{ "line": "Motor", "premium": 650000 }
]
},
{
"id": "C003",
"name": "Deccan Foods",
"renewal": "2027-06-18",
"policies": [
{ "line": "Health", "premium": 900000 }
]
}
],
"claims": [
{ "client": "C001", "line": "Health", "date": "2026-03-14", "paid": 310000, "outstanding": 0 },
{
"client": "C002",
"line": "Motor",
"date": "2026-07-02",
"paid": 180000,
"outstanding": 240000
},
{ "client": "C002", "line": "Motor", "date": "2026-09-21", "paid": 95000, "outstanding": 0 },
{
"client": "C003",
"line": "Health",
"date": "2026-10-05",
"paid": 120000,
"outstanding": 60000
}
]
}'const res = await fetch("https://api.moluscca.com/v1/insurance/loss-ratio", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "Demo book",
"currency": "INR",
"as_of": "2026-11-13",
"lines": {
"Motor": { "commission": 0.15 },
"Health": { "commission": 0.075 }
},
"clients": [
{
"id": "C001",
"name": "Kaveri Textiles",
"renewal": "2027-01-10",
"policies": [
{ "line": "Motor", "premium": 420000 },
{ "line": "Health", "premium": 1200000 }
]
},
{
"id": "C002",
"name": "Indus Logistics",
"renewal": "2026-12-02",
"policies": [
{ "line": "Motor", "premium": 650000 }
]
},
{
"id": "C003",
"name": "Deccan Foods",
"renewal": "2027-06-18",
"policies": [
{ "line": "Health", "premium": 900000 }
]
}
],
"claims": [
{ "client": "C001", "line": "Health", "date": "2026-03-14", "paid": 310000, "outstanding": 0 },
{
"client": "C002",
"line": "Motor",
"date": "2026-07-02",
"paid": 180000,
"outstanding": 240000
},
{ "client": "C002", "line": "Motor", "date": "2026-09-21", "paid": 95000, "outstanding": 0 },
{
"client": "C003",
"line": "Health",
"date": "2026-10-05",
"paid": 120000,
"outstanding": 60000
}
]
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/insurance/loss-ratio",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"name": "Demo book",
"currency": "INR",
"as_of": "2026-11-13",
"lines": {
"Motor": { "commission": 0.15 },
"Health": { "commission": 0.075 }
},
"clients": [
{
"id": "C001",
"name": "Kaveri Textiles",
"renewal": "2027-01-10",
"policies": [
{ "line": "Motor", "premium": 420000 },
{ "line": "Health", "premium": 1200000 }
]
},
{
"id": "C002",
"name": "Indus Logistics",
"renewal": "2026-12-02",
"policies": [
{ "line": "Motor", "premium": 650000 }
]
},
{
"id": "C003",
"name": "Deccan Foods",
"renewal": "2027-06-18",
"policies": [
{ "line": "Health", "premium": 900000 }
]
}
],
"claims": [
{ "client": "C001", "line": "Health", "date": "2026-03-14", "paid": 310000, "outstanding": 0 },
{
"client": "C002",
"line": "Motor",
"date": "2026-07-02",
"paid": 180000,
"outstanding": 240000
},
{ "client": "C002", "line": "Motor", "date": "2026-09-21", "paid": 95000, "outstanding": 0 },
{
"client": "C003",
"line": "Health",
"date": "2026-10-05",
"paid": 120000,
"outstanding": 60000
}
]
},
)
print(res.json())Response
{
"object": "loss_ratio",
"as_of": "2026-11-13",
"currency": "INR",
"window_months": 12,
"line": "All",
"gross_written_premium": 3170000,
"earned_premium": 3170000,
"commission": 318000,
"paid": 705000,
"outstanding": 300000,
"incurred": 1005000,
"loss_ratio": 0.317035,
"claim_frequency_per_100": 100,
"policies": 4,
"claims": 4,
"open_claims": 2,
"average_severity": 251250,
"by_line": [
{
"line": "Health",
"premium": 2100000,
"policies": 2,
"claims": 2,
"incurred": 490000,
"loss_ratio": 0.233333,
"commission": 157500
},
{
"line": "Motor",
"premium": 1070000,
"policies": 2,
"claims": 2,
"incurred": 515000,
"loss_ratio": 0.481308,
"commission": 160500
}
],
"clients": [
{
"id": "C001",
"name": "Kaveri Textiles",
"premium": 1620000,
"claims": 1,
"incurred": 310000,
"loss_ratio": 0.191358,
"credibility": 0.519231,
"credibility_loss_ratio": 0.242447,
"status": "Healthy",
"renewal": "2027-01-10"
},
{
"id": "C002",
"name": "Indus Logistics",
"premium": 650000,
"claims": 2,
"incurred": 515000,
"loss_ratio": 0.792308,
"credibility": 0.302326,
"credibility_loss_ratio": 0.575331,
"status": "Healthy",
"renewal": "2026-12-02"
},
{
"id": "C003",
"name": "Deccan Foods",
"premium": 900000,
"claims": 1,
"incurred": 180000,
"loss_ratio": 0.2,
"credibility": 0.375,
"credibility_loss_ratio": 0.220833,
"status": "Healthy",
"renewal": "2027-06-18"
}
],
"renewals_90_days": { "clients": 2, "premium": 2270000, "commission": 250500, "commission_at_risk": 0 },
"warnings": []
}
Business metrics
SaaS metrics
/v1/saas/metricsTurns customer revenue by month into MRR, churn, net revenue retention, LTV to CAC, payback and a forecast.
| Parameter | Type | Required | What it is |
|---|---|---|---|
months | string[] | yes | Like "2026-01", oldest first. |
customers | object[] | yes | [{ id, plan, mrr: [one number per month] }]. |
gross_margin | number | no | For LTV and payback, for example 0.8. |
spend | object | no | Sales and marketing spend by month, for CAC. |
options | object | no | forecast_months. |
curl https://api.moluscca.com/v1/saas/metrics \
-H "Authorization: Bearer $MOLUSCCA_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Demo SaaS",
"currency": "USD",
"gross_margin": 0.8,
"months": ["2026-06", "2026-07", "2026-08", "2026-09", "2026-10", "2026-11"],
"spend": {
"2026-06": 4000,
"2026-07": 4200,
"2026-08": 4500,
"2026-09": 4500,
"2026-10": 4800,
"2026-11": 5000
},
"customers": [
{ "id": "A1", "plan": "Growth", "mrr": [199, 199, 199, 299, 299, 299] },
{ "id": "A2", "plan": "Starter", "mrr": [49, 49, 49, 0, 0, 0] },
{ "id": "A3", "plan": "Scale", "mrr": [0, 799, 799, 799, 799, 799] },
{ "id": "A4", "plan": "Starter", "mrr": [0, 0, 49, 49, 49, 49] },
{ "id": "A5", "plan": "Growth", "mrr": [0, 0, 0, 199, 199, 149] },
{ "id": "A6", "plan": "Starter", "mrr": [49, 49, 49, 49, 49, 0] },
{ "id": "A7", "plan": "Growth", "mrr": [0, 0, 0, 0, 199, 199] }
],
"options": { "forecast_months": 3 }
}'const res = await fetch("https://api.moluscca.com/v1/saas/metrics", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MOLUSCCA_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "Demo SaaS",
"currency": "USD",
"gross_margin": 0.8,
"months": ["2026-06", "2026-07", "2026-08", "2026-09", "2026-10", "2026-11"],
"spend": {
"2026-06": 4000,
"2026-07": 4200,
"2026-08": 4500,
"2026-09": 4500,
"2026-10": 4800,
"2026-11": 5000
},
"customers": [
{ "id": "A1", "plan": "Growth", "mrr": [199, 199, 199, 299, 299, 299] },
{ "id": "A2", "plan": "Starter", "mrr": [49, 49, 49, 0, 0, 0] },
{ "id": "A3", "plan": "Scale", "mrr": [0, 799, 799, 799, 799, 799] },
{ "id": "A4", "plan": "Starter", "mrr": [0, 0, 49, 49, 49, 49] },
{ "id": "A5", "plan": "Growth", "mrr": [0, 0, 0, 199, 199, 149] },
{ "id": "A6", "plan": "Starter", "mrr": [49, 49, 49, 49, 49, 0] },
{ "id": "A7", "plan": "Growth", "mrr": [0, 0, 0, 0, 199, 199] }
],
"options": { "forecast_months": 3 }
})
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.moluscca.com/v1/saas/metrics",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
json={
"name": "Demo SaaS",
"currency": "USD",
"gross_margin": 0.8,
"months": ["2026-06", "2026-07", "2026-08", "2026-09", "2026-10", "2026-11"],
"spend": {
"2026-06": 4000,
"2026-07": 4200,
"2026-08": 4500,
"2026-09": 4500,
"2026-10": 4800,
"2026-11": 5000
},
"customers": [
{ "id": "A1", "plan": "Growth", "mrr": [199, 199, 199, 299, 299, 299] },
{ "id": "A2", "plan": "Starter", "mrr": [49, 49, 49, 0, 0, 0] },
{ "id": "A3", "plan": "Scale", "mrr": [0, 799, 799, 799, 799, 799] },
{ "id": "A4", "plan": "Starter", "mrr": [0, 0, 49, 49, 49, 49] },
{ "id": "A5", "plan": "Growth", "mrr": [0, 0, 0, 199, 199, 149] },
{ "id": "A6", "plan": "Starter", "mrr": [49, 49, 49, 49, 49, 0] },
{ "id": "A7", "plan": "Growth", "mrr": [0, 0, 0, 0, 199, 199] }
],
"options": { "forecast_months": 3 }
},
)
print(res.json())Response
{
"object": "saas_metrics",
"as_of": "2026-11",
"currency": "USD",
"mrr": 1495,
"arr": 17940,
"customers": 5,
"growth_mom": -0.062108,
"growth_yoy": null,
"nrr": null,
"grr": null,
"logo_churn": 0.073333,
"revenue_churn": 0.020981,
"arpa": 299,
"cac": 5750,
"ltv": 3261.82,
"ltv_cac": 0.567273,
"payback_months": 23.073836,
"quick_ratio": 0,
"quick_ratio_6m": 9.094595,
"last_month": {
"new": 0,
"expansion": 0,
"contraction": 50,
"churn": 49,
"new_customers": 0,
"churned_customers": 1
},
"plan_mix": [
{ "plan": "Scale", "mrr": 799, "customers": 1 },
{ "plan": "Growth", "mrr": 647, "customers": 3 },
{ "plan": "Starter", "mrr": 49, "customers": 1 }
],
"forecast": [
{ "month": 1, "p10": 1402.15, "p50": 1708.27, "p90": 5516.9 },
{ "month": 2, "p10": 1464.84, "p50": 1951.95, "p90": 6721.47 },
{ "month": 3, "p10": 1602.2, "p50": 2535.67, "p90": 19094.24 }
],
"warnings": ["Fewer than 13 months of data: year-on-year growth and 12-month retention cannot be calculated yet."]
}
Data
Climate series
/v1/climateMonthly irradiance, temperature, humidity and rainfall for a point in India. Early access, and the current dataset is a labelled sample.
| Parameter | Type | Required | What it is |
|---|---|---|---|
lat, lon | number | yes | The point. Must be within 50 km of a covered location. |
from, to | YYYY-MM | yes | Month range, inclusive. |
vars | string | no | Comma separated: irradiance, temperature, humidity, rainfall. Default all. |
curl "https://api.moluscca.com/v1/climate?lat=13.08&lon=80.27&from=2025-04&to=2025-06&vars=irradiance%2Crainfall" \ -H "Authorization: Bearer $MOLUSCCA_KEY"
const res = await fetch("https://api.moluscca.com/v1/climate?lat=13.08&lon=80.27&from=2025-04&to=2025-06&vars=irradiance%2Crainfall", {
headers: { Authorization: `Bearer ${process.env.MOLUSCCA_KEY}` }
});
const data = await res.json();import os, requests
res = requests.get(
"https://api.moluscca.com/v1/climate",
headers={"Authorization": f"Bearer {os.environ['MOLUSCCA_KEY']}"},
params={
"lat": "13.08",
"lon": "80.27",
"from": "2025-04",
"to": "2025-06",
"vars": "irradiance,rainfall"
},
)
print(res.json())Response
{
"object": "climate_series",
"sample": true,
"notice": "SYNTHETIC SAMPLE DATA. Generated from simple seasonal curves with seeded noise. Not observations. Do not use for decisions.",
"dataset_version": "sample-2026-11",
"resolution": "monthly",
"location": { "id": "IN-CHN", "name": "Chennai", "lat": 13.08, "lon": 80.27, "distance_km": 0 },
"from": "2025-04",
"to": "2025-06",
"units": {
"irradiance": "kWh/m2/day (global horizontal, monthly mean)",
"rainfall": "mm (monthly total)"
},
"series": [
{ "month": "2025-04", "irradiance": 6.79, "rainfall": 10 },
{ "month": "2025-05", "irradiance": 6, "rainfall": 34.3 },
{ "month": "2025-06", "irradiance": 5.15, "rainfall": 56.6 }
]
}
Health and usage
/v1/healthIs the service up. No key needed.
{
"status": "ok",
"product": "API",
"version": "0.1.0",
"uptime_seconds": 5120,
"endpoints": ["POST /v1/stats/describe", "..."]
}
/v1/usageYour plan and this month's credits.
{
"object": "usage",
"plan": "growth",
"period": "2026-11",
"used": 788,
"limit": 150000,
"remaining": 149212
}
/v1/samples/{name}Full sample inputs you can send straight back: portfolio-risk, loss-ratio or saas-metrics.
Versions and changes
The path starts with /v1. We add fields without notice, so ignore fields you do not know. Anything that would break your code gets a new version and at least six months of notice. See the changelog.