--- title: "How do I create a scenario?" slug: "how-do-i-create-a-scenario" updated: 2026-10-29T08:48:18Z published: 2026-10-29T08:48:18Z canonical: "support.lusid.com/how-do-i-create-a-scenario" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # How do I create a scenario? You can create a scenario that, for example, takes 20% off every equity price, moves sterling down 10% against the US dollar and raises US interest rates by 100bp. [See how to apply it to a valuation](/v1/docs/applying-a-scenario-to-a-valuation). Note the following: - You can build a scenario by hand, adding each shift yourself, or create one from a set of templates provided with LUSID, each of which helps model a common stress such as a parallel rise in rates. A scenario created from a template then becomes an ordinary scenario: it keeps no link to the template, and you can edit its shifts afterwards. - A scenario is identified by a scope and a code. Saving a scenario with the same scope and code replaces it, and LUSID records a new version. - A scenario can hold up to 1,000 shifts of any mix of types, or up to 100 if you edit it in the LUSID web app. [Note the order of shifts is significant](/v1/docs/scenario-reference). - LUSID checks a scenario when you save it, but cannot know whether a shift will match anything in your portfolios. A shift that matches nothing leaves the valuation unchanged and doesn’t report an error, so [check what your scenario shifts](/v1/docs/how-do-i-create-a-scenario#checking-what-a-scenario-will-shift) before you rely on it. - You can’t currently create scenarios using Luminesce. ## Methods **LUSID web app** To create a scenario by hand: 1. Navigate to **Portfolio Management > Scenarios** and click **Create Scenario**. 2. On the **Basic Details** tab, enter a **Scope** and **Code** and choose a **Scenario type**. You can also enter a **Display name** and **Description**. 3. On the **Shifts** tab, click **Add shift**, choose a **Scenario shift type** and [fill in the fields](/v1/docs/scenario-reference) for that type. Repeat for each shift you want to add. 4. Click **Create**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-13JNWJFA.png?sv=2026-02-06&spr=https&st=2026-10-29T10%3A47%3A53Z&se=2026-10-29T11%3A47%3A53Z&sr=c&sp=r&sig=Fd%2FSukL4pXYuXPwEvKTOqx6TUVIln7IYx89rmSNmVpc%3D) To create a scenario from a template: 1. Navigate to **Portfolio Management > Scenarios**, click the arrow next to **Create Scenario** and choose a template: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-V378PN80.png?sv=2026-02-06&spr=https&st=2026-10-29T10%3A47%3A53Z&se=2026-10-29T11%3A47%3A53Z&sr=c&sp=r&sig=Fd%2FSukL4pXYuXPwEvKTOqx6TUVIln7IYx89rmSNmVpc%3D) 2. Enter a **Scope** and **Code**, and optionally a **Display name** and **Description**. To see what the template does, hover over the information icon next to the **Template** field. 3. Fill in the [template parameters](/v1/docs/scenario-reference#templates). The label of each parameter shows its unit, for example basis points. 4. Click **Create**: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-6MI6MJ9Z.png?sv=2026-02-06&spr=https&st=2026-10-29T10%3A47%3A53Z&se=2026-10-29T11%3A47%3A53Z&sr=c&sp=r&sig=Fd%2FSukL4pXYuXPwEvKTOqx6TUVIln7IYx89rmSNmVpc%3D) Note the following: - To edit, duplicate or delete a scenario, use the actions on its row in the list. - The web app can’t set a scenario’s short code so LUSID generates one for you (see below). - To preview a scenario, you must use the LUSID API. **LUSID API** Call the [UpsertScenario](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/UpsertScenario/) API. Consider the following example, which creates a scenario modelling a 2008-style market crash: - The first shift takes 20% off the price of every equity. Its filter selects instruments by their [asset class](/v1/docs/how-does-lusid-categorise-instruments-into-asset-classes). - The second and third shifts take 30% off the prices of two banks, identified by their LUIDs. When a shift names an instrument directly, it replaces any filter-based shift on the same price, so these two shares fall 30% rather than 20% and then a further 30%. - The fourth shift moves the GBP/USD exchange rate down 10%. - The fifth shift raises every USD interest rate curve by 100bp across its whole length. - The sixth shift adds 5 volatility points (0.05) to every equity volatility surface. For more information on `scenarioShiftType` fields, see the [reference](/v1/docs/scenario-reference). ```json curl -X POST 'https://.lusid.com/api/api/scenarios'  -H 'Authorization: Bearer '  -H 'Content-Type: application/json-patch+json'  -d '{  "scenario": {    "scope": "ScenarioTutorial",    "code": "MarketCrash",    "displayName": "2008-style market crash",    "description": "Equities -20%, JPMorgan and HSBC -30%, GBP/USD -10%, USD rates +100bp, equity vol +5 points",    "shortCode": "CRASH08",    "scenarioType": "Historical",    "shifts": [      {"scenarioShiftType": "PriceShiftDefinition", "filter": "assetClass eq 'Equities'", "amount": -20, "shiftType": "percentage", "quoteType": "Price"},      {"scenarioShiftType": "PriceShiftDefinition", "instrument": "LUID_00003HDL", "amount": -30, "shiftType": "percentage", "quoteType": "Price"},      {"scenarioShiftType": "PriceShiftDefinition", "instrument": "LUID_00003HDG", "amount": -30, "shiftType": "percentage", "quoteType": "Price"},      {"scenarioShiftType": "FxShiftDefinition", "currencyPair": "GBP/USD", "amount": -10, "shiftType": "percentage"},      {"scenarioShiftType": "RateCurveShiftDefinition", "ccy": "USD", "amount": 100, "shiftType": "parallel", "scale": "Bps"},      {"scenarioShiftType": "VolSurfaceShiftDefinition", "instrument": "EquityVol.*", "amount": 0.05, "shiftType": "absolute"}    ]  } }' ``` To create a scenario from a template, call the [CreateScenarioFromTemplate](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/CreateScenarioFromTemplate) API, passing the scope in the URL. To list the [available templates](/v1/docs/scenario-reference#templates) and their parameters, call the [ListScenarioTemplates](https://www.lusid.com/docs/api#operation/ListScenarioTemplates) API. For example, to create a scenario using the `RatesUp` template that raises every USD rate curve by 100bp: ```json curl -X POST 'https://.lusid.com/api/api/scenarios/ScenarioTutorial/$fromTemplate'  -H 'Authorization: Bearer '  -H 'Content-Type: application/json-patch+json'  -d '{  "template": "RatesUp",  "code": "UsdRatesUp100",  "displayName": "USD rates +100bp",  "parameters": {    "ccy": "USD",    "amount": "100"  } }' ``` Note the following: - Template names aren’t case-sensitive, but parameter names are. LUSID rejects a parameter the template doesn’t recognise. - Parameter values are always strings, even for amounts. - If you omit `displayName` and `description`, LUSID generates them from the template, for example “Rates +50bps”. ## Request fields This section supplements the [API documentation](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/UpsertScenario) and on-screen help text in the LUSID web app. | Mandatory fields | Explanation | | --- | --- | | `scope`, `code` | Together these uniquely identify the scenario. Each can be up to 64 characters long and contain letters, numbers, hyphens and underscores. | | `scenarioType` | One of `Historical`, `Regulatory` or `Hypothetical`. This value is case-sensitive. It helps you organise scenarios and has no effect on valuation. The web app defaults to `Hypothetical`. | | `shifts` | The list of shifts, each with a `scenarioShiftType` and the [fields for that type](/v1/docs/scenario-reference). Note the order of shifts is significant. You can save a scenario with no shifts, but it changes nothing. | | Selected optional fields | | | `displayName`, `description` | A friendly name and a description, each up to 1,024 characters. The web app shows the display name in its scenario pickers. | | `shortCode` | A label of up to 10 letters, numbers, hyphens and underscores, for example `CRASH08`. The web app uses it to label scenario columns in valuation reports. If you omit it, LUSID generates one from the display name each time you retrieve the scenario: the first four-digit year it finds, plus an acronym of up to four letters. For example, “Global Financial Crisis (2008) replay” produces `GFCR2008`. | ## Checking what a scenario will shift A shift that matches nothing doesn’t cause an error. To check what a scenario shifts before relying on it, call the [PreviewScenario](https://www.lusid.com/docs/api#operation/PreviewScenario) API with a recipe, one or more portfolios, an effective date and the scenario. LUSID locates the market data those portfolios need, applies the scenario, and returns each piece of market data it shifted, without valuing anything, for example: ```json curl -X POST 'https://.lusid.com/api/api/scenarios/$preview'  -H 'Authorization: Bearer '  -H 'Content-Type: application/json-patch+json'  -d '{  "recipeId": {"scope": "ScenarioTutorial", "code": "Recipe"},  "portfolioEntityIds": [{"scope": "ScenarioTutorial", "code": "CRASH-USD", "portfolioEntityType": "SinglePortfolio"}],  "effectiveAt": "2026-10-01T00:00:00Z",  "scenario": {"scope": "ScenarioTutorial", "code": "MarketCrash"} }' ``` Note the following in the response: - Each entry in `applied` names the shift, the market data it changed (`target`), and the value before and after. Values are shown for prices and FX rates, but not for curves and volatility surfaces. - `skipped` lists market data a shift matched but couldn’t change, with a reason. - If a shift you expected is missing from `applied`, it matched nothing. Check its target, for example that the filter uses `'Equities'` rather than `'Equity'`. ```json {  "applied": [    {      "effectiveAt": "2026-10-01T00:00:00+00:00",      "shift": "PriceShift on 'LUID_00003HDL'",      "target": "Quote:{ {LusidInstrumentId: LUID_00003HDL}, {ClientInternal: JPM} }:2026-10-01T00:00:00.0000000+00:00",      "valueBefore": 250.0,      "valueAfter": 175.0    },    ...  ],  "skipped": [] } ``` You can also preview shifts without saving them first: instead of `scenario`, supply a `shifts` list. In a preview only, you can leave out each shift’s `amount` to see what it would match. When you value a portfolio using the API, the response includes the same information in its `scenarioDiagnostics` section. ## Subsequent updates To change a scenario, select **Edit** in the web app, or call the [UpsertScenario](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/UpsertScenario/) API again with the same `scope` and `code`. An upsert replaces the whole scenario, so include every shift you want to keep. Each save creates a new version. To see the history, call the [ListScenarioVersions](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/ListScenarioVersions) API. To retrieve an earlier version, call [GetScenario](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/GetScenario) with an `asAt` date. A valuation uses the version of the scenario that was current at the valuation’s as-at time. To value against a particular version through the [GetValuation](https://www.lusid.com/docs/api/lusid/endpoints/aggregation/GetValuation) API, supply an `asAt` with the scenario’s scope and code. To delete a scenario, select **Delete** in the web app or call the [DeleteScenario](https://www.lusid.com/docs/api/lusid/endpoints/scenarios/DeleteScenario) API.