How do I create a scenario?

  • Published on Oct 29, 2026
Prev Next

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.

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.

  • 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 before you rely on it.

  • You can’t currently create scenarios using Luminesce.

Methods

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 for that type. Repeat for each shift you want to add.

  4. Click Create:


To create a scenario from a template:

  1. Navigate to Portfolio Management > Scenarios, click the arrow next to Create Scenario and choose a template:

  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. The label of each parameter shows its unit, for example basis points.

  4. Click Create:

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.

Call the 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.

  • 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.

curl -X POST 'https://<your-domain>.lusid.com/api/api/scenarios'
  -H 'Authorization: Bearer <your-API-access-token>'
  -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 API, passing the scope in the URL. To list the available templates and their parameters, call the ListScenarioTemplates API. For example, to create a scenario using the RatesUp template that raises every USD rate curve by 100bp:

curl -X POST 'https://<your-domain>.lusid.com/api/api/scenarios/ScenarioTutorial/$fromTemplate'
  -H 'Authorization: Bearer <your-API-access-token>'
  -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 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. 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 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:

curl -X POST 'https://<your-domain>.lusid.com/api/api/scenarios/$preview'
  -H 'Authorization: Bearer <your-API-access-token>'
  -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'.

{
  "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 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 API. To retrieve an earlier version, call 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 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 API.

© 2025 FINBOURNE Technology