Results Reference

When you download a completed scenario, you get up to three payloads: a small metadata.json summary (the headline figures — final capital, return, trade counts — also shown by scenario get and in the Read Workflow), the full timeseries.json equity curve, and the per-trade trades.json log. This page documents what's inside timeseries.json and trades.json and how every headline metric is computed.

Result files exist only for a scenario that reached COMPLETE — a FAILED or CANCELLED run produces no downloadable results.

A few conventions apply throughout:

• Timestamps are Unix epoch milliseconds in UTC — divide by 1000 for seconds.
• Decimal money and price values are encoded as JSON strings (e.g. "1.08500"), not numbers, so exact scale survives the round-trip. Parse them as decimals, not floats.
• Amounts are in the account's denomination currency (the currency all subscribed instruments settle in).

Timeseries file

timeseries.json is the equity curve. The engine stores it as four parallel arrays — timestamps, units, nav, and margin_used — with one value per data point in each, aligned by index: element i of every array describes the same moment. The three decimal columns are arrays of decimal strings; timestamps is an array of integers.

The number of data points is adaptive, not fixed-interval — the engine samples on market activity — so don't assume a uniform time step between consecutive timestamps.

A three-point example (element i of each array is the same moment):

{
  "timestamps": [1704067200000, 1704067260000, 1704067320000],
  "units": ["100000.00", "100000.00", "100120.50"],
  "nav": ["100000.00", "100085.00", "100120.50"],
  "margin_used": ["0", "2000.00", "0"]
}

Trades file

trades.json is an envelope around one array — { "trades": [ ... ] } — with one object per trade lot, sorted by id for deterministic output. A trade that is still open when the run ends omits every close-side field, so open trades have no close_price, closed_at, realized_pnl, or close_reason. Optional fields below are also absent on legacy trades recorded before the field existed, or on zero-fee configurations for the commission fields.

Realized P&L is notional: units × (close_price − open_price) for a Long, and units × (open_price − close_price) for a Short. Because open_price and close_price are the post-slippage fill prices, slippage and spread are already reflected in the P&L; commissions are reported separately in entry_commission / exit_commission.

An example with one closed trade and one still-open trade — note the open trade omits every close-side field:

{
  "trades": [
    {
      "id": "trade-000001",
      "state": "Closed",
      "instrument_symbol": "F:EURUSD",
      "open_price": "1.08525",
      "base_open_price": "1.08500",
      "open_slippage_bps": "2.3",
      "close_price": "1.09010",
      "base_close_price": "1.09000",
      "close_slippage_bps": "0.9",
      "entry_commission": "2.50",
      "exit_commission": "2.50",
      "units": "10000",
      "direction": "Long",
      "opened_at": 1704067200000,
      "opened_by_order_id": "ord_a1b2",
      "closed_at": 1704153600000,
      "closed_by_order_id": "ord_c3d4",
      "realized_pnl": "48.50",
      "close_reason": "Normal"
    },
    {
      "id": "trade-000002",
      "state": "Open",
      "instrument_symbol": "F:GBPUSD",
      "open_price": "1.26010",
      "base_open_price": "1.26000",
      "open_slippage_bps": "0.8",
      "units": "5000",
      "direction": "Short",
      "opened_at": 1704070800000,
      "opened_by_order_id": "ord_e5f6"
    }
  ]
}

Headline metrics

These are the top-line performance figures reported for a completed scenario (see Write Workflow → Read the results for the scenario get shape). All are derived from the nav (equity) curve and the closed trades — you don't compute them yourself.

Percentage metrics are expressed as percentages, not fractions — 12.45 means 12.45%, not 1245%. Monetary metrics (netPnl, grossPnl) are in the account's denomination currency.

Additional metrics

The full metrics object carries more detail. Percentages follow the same convention; the risk-adjusted and per-trade fields are omitted, each with a companion …Reason, when there isn't enough data to compute them (e.g. a flat curve, or a run with no losing trades). The …Reason value is one of insufficient_data_points, zero_standard_deviation, no_negative_returns, no_winning_trades, no_losing_trades, or no_closed_trades.

Related

• Read Workflow — how to download these files.
• Execution & Costs — how spread, slippage, commission, and funding enter the fill prices these files record.
• Available Instruments — the symbols that appear in instrument_symbol.