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

# run_grid_job

> Sweep pipeline parameters and compare every variant in one run

## Overview

`run_grid_job` runs the whole research pipeline once per parameter combination and returns a single
artifact with the metrics of every variant side by side.

It is the one tool that needs no upstream step: give it tickers and a date window and it downloads
the prices itself. Pass a `data_extractor_*.json` link instead if you already have the data.

Two pipelines:

* **short** — data → portfolio construction → backtest. No features, no ML.
* **long** — data → features → ML or deep learning → portfolio construction → backtest.

A sweep is heavy by design: every variant is a full backtest, and a large grid can run for up to
two hours.

***

## Parameters

<ParamField body="config" type="object" required>
  Grid configuration. Pass `{}` to run the bundled defaults — short pipeline, one variant.

  <Expandable title="config fields">
    <ParamField body="pipeline_mode" type="string">
      `"short"` (data → PO → backtest) or `"long"` (adds features and a forecasting model).
      Default: `"short"`.
    </ParamField>

    <ParamField body="block_name" type="string">
      Which step is swept. `"POgrid"` for the short pipeline; `"FeaturesGrid"`, `"MLgrid"` or
      `"DeepLearningGrid"` for the long one.
    </ParamField>

    <ParamField body="returns_engine" type="string">
      Long pipeline only: `"ml"`, `"dl"` or `"none"`.
    </ParamField>

    <ParamField body="grid_limits" type="object">
      Guard rails — `max_axes` and `max_combinations`. A sweep that exceeds them is refused
      before anything runs, so raise them deliberately rather than by accident.
    </ParamField>

    <ParamField body="Data params" type="object">
      Tickers and date window when the job downloads the data itself: `Tickers` (a list of
      symbols), `Data_source`, `Learning_start`, `Testing_end`.
    </ParamField>

    <ParamField body="block_params" type="object">
      Per-step settings. `fixed_params` holds what stays constant; every value in `grid_params`
      is a **list**, and their cartesian product forms the variants.
    </ParamField>

    <ParamField body="variant_reports" type="object">
      Per-variant HTML reports — equity curve, quantstats, bootstrap CI, riskfolio. On by default.
      A report that fails marks its variant failed, so switch them off for large sweeps.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="input_url" type="string">
  Optional blob URL to a `data_extractor_*.json` file. When omitted, the job downloads the prices
  described in `Data params`.
</ParamField>

***

## Returns

```json theme={null}
{
  "status": "Succeeded",
  "output_url": "https://stqsnpprod.blob.core.windows.net/data/grid_engine_9a1b2c3d4e5f.json",
  "output_name": "grid_engine_9a1b2c3d4e5f.json",
  "execution_name": "grid-worker-abc123xyz"
}
```

The artifact holds `run_id`, `pipeline_mode`, `n_ok` / `n_variants`, and a `variants` array with the
parameters, metrics and status of each variant. A variant whose backtest succeeded but whose HTML
report failed has status `report_error` and keeps its metrics — read them rather than discarding the
variant.

***

## Example — sweep the rebalance frequency

```json theme={null}
{
  "config": {
    "block_params": {
      "POgrid": {
        "grid_config": {
          "grid_params": { "rebalance_frequency": [1, 5, 21] }
        }
      }
    }
  }
}
```

## Example — explicit pipeline and data window

```json theme={null}
{
  "config": {
    "pipeline_mode": "short",
    "block_name": "POgrid",
    "returns_engine": "none",
    "grid_limits": { "max_axes": 3, "max_combinations": 100 },
    "Data params": {
      "Tickers": ["AAPL", "MSFT", "JPM"],
      "Data_source": "yahoo",
      "Learning_start": "2022-01-01",
      "Testing_end": "2025-01-01"
    },
    "block_params": {
      "POgrid": {
        "grid_config": {
          "fixed_params": { "methods": "equal_weighted" },
          "grid_params": { "rebalance_frequency": [1, 5, 21] }
        }
      }
    }
  }
}
```

***

## Next Step

Compare the variants, then rerun the winning combination as a normal chain
([`run_po_job`](/tools/po-job) → [`run_trading_job`](/tools/trading-job)) when you want charts and
reports for it. Best variants are a search result, not evidence — confirm one on a window you did
not sweep over.