MesoSim Backtest API

The MesoSim Backtest API provides programmatic access to create, manage, and analyze backtests. This API allows you to integrate MesoSim's powerful options backtesting capabilities into your own workflows and applications.

Authentication

All API endpoints require authentication using JWT Bearer token. You must include your API key in the Authorization header of all requests.

You can create an API key in the MesoSim web interface under the API Keys section.

Authorization: Bearer {your_api_key}

API access is available to users using a paid seat from the cluster.

API Endpoints

Create a New Backtest

Creates a new backtest job based on your strategy definition.

PUT /api/v1/backtest/new

Request Body

{
  "StrategyDefinition": {
    "StrategyName": "ShortPut",
    "Backtest": {
      "Name": "string",  // Optional - a random name will be generated if set to "generate"
      "Start": "YYYY-MM-DDT00:00:00",
      "End": "YYYY-MM-DDT23:59:59",
      "Cash": "125000"
    },
    "Symbol": "SPX",
    "Structure": { /* legs, expirations, selectors */ },
    "Entry": { /* schedule, conditions, vars */ },
    "Adjustment": null,
    "Exit": { /* schedule, conditions, targets */ },
    "ExternalData": null,
    "Settings": { "Sim": { /* fill, commission */ }, "Core": { /* margin, constraints */ } }
  },
  "Shared": false
}

Responses

Status Code	Description
201	Backtest created successfully
401	Unauthorized - Invalid or missing API key
429	Too many requests - Rate limit exceeded
500	Internal server error
503	Backend service unavailable

Response Body (201)

{
  "BacktestId": "string",
  "Name": "string"
}

List Backtests

Retrieves a list of your backtests filtered by date range and status.

GET /api/v1/backtests

Query Parameters

Parameter	Type	Required	Description
start	DateTime	Yes	Start date for filtering backtests
end	DateTime	Yes	End date for filtering backtests
page	integer	Yes	Page number (zero-based)
pageSize	integer	No	Number of results per page (max: 1000, default: 1000)
includeAnalytics	boolean	No	Include performance metrics in response (default: false)
status	string	No	Filter by backtest status ('All', 'Created', 'Started', 'Finished', 'Failed'; default: 'All')

Responses

Status Code	Description
200	Success
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing API key
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

[
  {
    "Id": "string",
    "Name": "string",
    "StrategyName": "string",
    "Shared": true,
    "State": "Finished",
    "CreatedAt": "string",
    "StartedAt": "string",
    "FinishedAt": "string",
    "/* additional fields if includeAnalytics=true */"
  }
]

Get Backtest Analytics

Retrieves performance metrics for a specific backtest.

GET /api/v1/backtest/{id}/analytics

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
405	Method not allowed - Backtest failed
425	Too early - Backtest is still running
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

Detailed analytics object containing performance metrics for the backtest.

{
  "StartPeriod": "2021-01-04T00:00:00",
  "EndPeriod": "2025-03-24T00:00:00",
  "StratTradeCnt": 210,
  "StratWinCnt": 135,
  "StratLossCnt": 75,
  "StratAdjustmentCnt": 0,
  "StratPtHitCnt": 0,
  "StratSlHitCnt": 0,
  "StratMaxDitReachedCnt": 0,
  "StratSettlementCnt": 0,
  "StratAvgDaysInTrade": 3.5667,
  "StratAlpha": 0.4,
  "StratBeta": -0.06,
  "StratCagrPct": 46.66,
  "StratCumRet": 403.22,
  "StratMaxDd": -13.4,
  "StratAvgDd": -0.47,
  "StratAvgDdDays": 2,
  "StratAvgUpMonth": 3.89,
  "StratAvgDownMonth": -5.4,
  "StratLongestDdDays": 160,
  "StratInformRatio": 0.01,
  "StratSharpe": 2.56,
  "StratProbSharpe": 100,
  "StratSmartSharpe": 2.45,
  "StratSortino": 4.49,
  "StratSmartSortino": 4.3,
  "StratTreynor": -7269.28,
  "StratCalmar": 3.48,
  "StratOmega": 1.22,
  "StratRSquared": 0,
  "StratProfitFactor": 1.22,
  "StratKellyCriterion": 9.22,
  "StratAnnVolatility": 15.43,
  "BmCagrPct": 10.7,
  "BmCumRet": 53.55,
  "BmMaxDd": -27.37,
  "BmAvgDd": -0.33,
  "BmAvgDdDays": 2,
  "BmAvgUpMonth": 3.42,
  "BmAvgDownMonth": -1.8,
  "BmLongestDdDays": 745,
  "BmInformRatio": 0.01,
  "BmSharpe": 0.72,
  "BmProbSharpe": 93.09,
  "BmSmartSharpe": 0.69,
  "BmSortino": 1.01,
  "BmSmartSortino": 0.97,
  "BmTreynor": null,
  "BmCalmar": 0.39,
  "BmOmega": 1.22,
  "BmRSquared": 0,
  "BmProfitFactor": 1.02,
  "BmKellyCriterion": -1.73,
  "BmAnnVolatility": 15.78
}

Get Strategy Definition

Retrieves the original strategy definition (v3) for a specific backtest.

GET /api/v1/backtest/{id}/strategy-definition

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

The original v3 strategy definition object.

{
  "StrategyName": "ShortPut",
  "Backtest": {
    "Name": "api-test",
    "Start": "2022-01-01T00:00:00",
    "End": "2023-12-31T23:59:59",
    "Cash": "100000"
  },
  "Description": "",
  "Symbol": "SPX",
  "Structure": { /* ... */ },
  "Entry": { /* ... */ },
  "Adjustment": null,
  "Exit": { /* ... */ },
  "ExternalData": null,
  "Settings": { "Sim": { /* ... */ }, "Core": { /* ... */ } }
}

Get Backtest Events

Retrieves the events (fills, orders, etc.) for a specific backtest.

GET /api/v1/backtest/{id}/events

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Query Parameters

Parameter	Type	Required	Description
start	DateTime	No	Filter events after this simulation time
end	DateTime	No	Filter events before this simulation time
eventType	string	No	Filter by event type

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

List of blotter event objects matching the specified criteria.

Get Backtest NAVs

Retrieves NAV (Net Asset Value) data in CSV format for a specific backtest.

GET /api/v1/backtest/{id}/navs

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Responses

Status Code	Description
200	Success - Returns CSV content
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

CSV data containing backtest NAV values.

Get External Data

Retrieves the external data used in a specific backtest (if any).

GET /api/v1/backtest/{id}/external-data

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Responses

Status Code	Description
200	Success - Returns zip file
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID or external data doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

ZIP file containing the external data used in the backtest.

Get Sharing Status

Retrieves the sharing status for a specific backtest.

GET /api/v1/backtest/{id}/sharing

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Response Body (200)

{
  "SharingEnabled": boolean
}

Update Sharing Status

Updates the sharing status for a specific backtest.

POST /api/v1/backtest/{id}/sharing

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Query Parameters

Parameter	Type	Required	Description
sharingEnabled	boolean	Yes	New sharing status

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Delete Backtest

Deletes a specific backtest.

DELETE /api/v1/backtest/{id}

Path Parameters

Parameter	Type	Description
id	string	Backtest ID

Query Parameters

Parameter	Type	Required	Description
deleteMode	string	Yes	Deletion mode: 'Full', 'Details', or 'Soft'

Responses

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this backtest
404	Not found - Backtest ID doesn't exist
429	Too many requests - Rate limit exceeded
500	Internal server error

Error Handling

All errors are returned with an appropriate HTTP status code. Common status codes:

• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Access denied to the requested resource
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Unexpected server error

Rate Limiting

The API implements rate limiting to ensure fair usage. If you exceed the rate limit, requests will fail with a 429 (Too Many Requests) status code. Back off and retry your request after a delay.

Using from Python

Merlin provides helper functions to conveniently access MesoSim APIs from Python. The functions handle parallel execution so that the cluster can be used efficiently.