> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useforecast.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run research backtest

<RequestExample dropdown>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.forecast.example/api/v1/research/backtest' \
    --header 'Authorization: Bearer USER_JWT' \
    --header 'Content-Type: application/json' \
    --data '{
      "entry_executable": {
        "name": "sample strategy"
      },
      "objective": "avg_pnl"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.forecast.example/api/v1/research/backtest', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer USER_JWT',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entry_executable: {
        name: 'sample strategy'
      },
      objective: 'avg_pnl'
    })
  });

  const report = await response.json();
  ```

  ```python Python theme={null}
  import requests

  report = requests.post(
      "https://api.forecast.example/api/v1/research/backtest",
      headers={
          "Authorization": "Bearer USER_JWT",
          "Content-Type": "application/json",
      },
      json={
          "entry_executable": {
              "name": "sample strategy"
          },
          "objective": "avg_pnl",
      },
      timeout=60,
  ).json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "schemaVersion": 2,
    "strategy": {
      "name": "sample strategy",
      "kind": "signal_filter",
      "featuresUsed": 12,
      "candidatesUsed": 8
    },
    "metrics": {
      "n": 184,
      "avg_pnl": 4.28
    },
    "verdict": {
      "grade": "B"
    }
  }
  ```
</ResponseExample>

Use this endpoint to run a concrete strategy against the R2-backed research stack. This is an execution endpoint, not just an object read.

## Body fields

<ParamField body="entry_executable" type="object" required>
  Strategy definition to evaluate. The current implementation requires this field.
</ParamField>

<ParamField body="objective" type="string">
  Optimization objective, such as `avg_pnl`.
</ParamField>

<ParamField body="since" type="number">
  Optional lower time bound in epoch milliseconds.
</ParamField>

<ParamField body="until" type="number">
  Optional upper time bound in epoch milliseconds.
</ParamField>

<ParamField body="tradeSizeUsd" type="number">
  Optional fixed trade size normalization for report output.
</ParamField>

## Response fields

<ResponseField name="schemaVersion" type="number" required>
  Schema version for the analytics report.
</ResponseField>

<ResponseField name="strategy" type="object" required>
  Summary of the tested strategy and feature usage.
</ResponseField>

<ResponseField name="metrics" type="object">
  Core report metrics for the tested strategy.
</ResponseField>

<ResponseField name="verdict" type="object">
  Final report verdict for the run.
</ResponseField>