Skip to main content

QuantStats Endpoints

Overview​

The QuantStats API endpoints provide comprehensive performance analysis for investment strategies. These endpoints leverage the popular QuantStats library to generate detailed performance reports and metrics, allowing you to evaluate your trading strategies against benchmarks.

The API supports two input formats:

  1. JSON payload with datetime and price data
  2. CSV-formatted data with headers and values

API Endpoints​

Generate Tearsheet from JSON​

POST /quantstats/v1/tearsheet-from-json

This endpoint takes a JSON structure containing datetime, strategy NAV, and benchmark price data and returns a fully formatted HTML tearsheet containing visualizations and metrics.

Request Format​

The request body should contain a JSON object with an array of data points:

{
  "rows": [
    {
      "dateTime": "2023-01-01",
      "strategyNAV": 1000.0,
      "benchmarkPrice": 4000.0
    },
    {
      "dateTime": "2023-01-02",
      "strategyNAV": 1005.0,
      "benchmarkPrice": 4015.0
    },
    ...
  ]
}

Each row must contain:

  • dateTime: Date or datetime in ISO format (YYYY-MM-DD)
  • strategyNAV: The net asset value of your strategy
  • benchmarkPrice: The price of your benchmark (typically an index like S&P 500)

Response​

The endpoint returns an HTML document with the complete tearsheet, including:

  • Return metrics (CAGR, Sharpe ratio, etc.)
  • Risk metrics (volatility, drawdown, etc.)
  • Comparative analysis with benchmark
  • Performance visualizations
  • Monthly and yearly breakdowns
  • Distribution analysis

Generate Tearsheet from CSV​

POST /quantstats/v1/tearsheet-from-csv

This endpoint accepts CSV-formatted data directly in the request body and returns the same HTML tearsheet as the JSON version.

Request Format​

The request should be formatted as plain text CSV with headers:

DateTime,StrategyNAV,BenchmarkPrice
2023-01-01,1000.0,4000.0
2023-01-02,1005.0,4015.0
...

The header row must match exactly as shown, and at least 5 rows of data are required.

Response​

Same HTML tearsheet as described for the JSON endpoint.

Get Metrics from JSON​

POST /quantstats/v1/metrics-from-json

This endpoint takes the same JSON input as the tearsheet endpoint but returns only the calculated metrics as structured JSON rather than a full HTML report.

Request Format​

Same JSON format as the tearsheet endpoint.

Response Format​

The response is a JSON object containing two sets of metrics:

{
  "strategy": {
    "startPeriod": "2023-01-01T00:00:00",
    "endPeriod": "2023-12-31T00:00:00",
    "riskFreeRate": 0.0,
    "timeInMarket": 1.0,
    "cumulativeReturn": 0.25,
    "cagrPercent": 26.24,
    "sharpe": 1.85,
    "probSharpeRatio": 0.95,
    "smartSharpe": 1.76,
    "sortino": 2.94,
    "smartSortino": 2.81,
    "omega": 1.76,
    "maxDrawdown": -0.12,
    ...
  },
  "benchmark": {
    // Similar metrics for the benchmark
    ...
  }
}

Key metrics include:

Get Metrics from CSV​

POST /quantstats/v1/metrics-from-csv

This endpoint accepts CSV-formatted data directly in the request body and returns the same metrics structure as the JSON metrics endpoint.

Request Format​

Same CSV format as the tearsheet-from-csv endpoint.

Response Format​

Same JSON metrics structure as described for the metrics-from-json endpoint.

Example Usage​

Generating a Full Tearsheet​

import requests
import json

data = {
  "rows": [
    {"dateTime": "2023-01-01", "strategyNAV": 1000.0, "benchmarkPrice": 4000.0},
    {"dateTime": "2023-01-02", "strategyNAV": 1005.0, "benchmarkPrice": 4015.0},
    # Add more data rows...
  ]
}

response = requests.post(
  "https://q-api.example-customer.mesosim.io/quantstats/v1/tearsheet-from-json",
  json=data,
  headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)

# Save the HTML tearsheet to a file
with open("strategy_tearsheet.html", "wb") as f:
  f.write(response.content)

Getting Just the Metrics​

import requests
import json

data = {
  "rows": [
    {"dateTime": "2023-01-01", "strategyNAV": 1000.0, "benchmarkPrice": 4000.0},
    {"dateTime": "2023-01-02", "strategyNAV": 1005.0, "benchmarkPrice": 4015.0},
    # Add more data rows...
  ]
}

response = requests.post(
  "https://q-api.example-customer.mesosim.io/quantstats/v1/metrics-from-json",
  json=data,
  headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)

metrics = response.json()
print(f"Strategy Sharpe Ratio: {metrics['strategy']['sharpe']}")
print(f"Strategy Max Drawdown: {metrics['strategy']['maxDrawdown']}")

Requirements and Limitations​

  • A minimum of 5 data points is required
  • Dates should be in chronological order
  • The API performs basic validation but assumes inputs represent valid financial time series
  • For optimal visualization, providing at least several months of data is recommended
  • All responses include appropriate HTTP headers for proper handling by browsers