List allocation methods

Operation id: list_allocation_methods — REST POST /api/v1/research/list_allocation_methods, MCP tool list_allocation_methods.

When should you use List allocation methods?

• The user asks which ways of weighting holdings exist, or what a method can be tuned with.
• Before building or editing a strategy, to pick a method the user's plan includes.

Use another operation when:

• You need every field of a strategy, not only its allocation methods — use describe_portfolio_model instead.

What parameters does List allocation methods take?

• level (optional; string; one of portfolio, model, both; default "both") — Which level's methods to list: portfolio for the Combined level, model for the strategy level, both for every method at either level.
• query (optional; string; 1–80 characters) — Words to look for, ignoring case, in each method's name and description; methods that do not contain them are left out.

What does List allocation methods return?

The result object holds the fields below. Every result also carries a text summary, the assumed values and the dataVersion, as the reference describes.

• methods (list) — The matching methods, in the order the app's method picker shows them.
• methods[].id (string) — The method's stable public id, in snake_case.
• methods[].name (string; at least 1 characters) — The method's name as the app shows it.
• methods[].description (string; at least 1 characters) — The app's one-line description of what the method does.
• methods[].levels (list) — The levels the method works at: portfolio (the Combined level), model (the strategy level), or both.
• methods[].parameters (list) — The method's own settings. Settings every method shares, such as the lookback and leverage, are described by describe_portfolio_model.
• methods[].parameters[].name (string) — The setting's public name, in camelCase.
• methods[].parameters[].label (string; at least 1 characters) — The setting's label in the app.
• methods[].parameters[].levels (list) — The levels this entry describes: portfolio (the Combined level), model (the strategy level) or both. A setting whose type, bounds, allowed values or plan differ between the levels is listed once per level, under the same name.
• methods[].parameters[].type (string; one of number, integer, boolean, enum, string, list) — number, integer, boolean, enum, string or list. A string setting is an identifier, such as the permaTicker of the reference instrument a Mimicking strategy tracks; a list setting is a list of numbers, such as the ranking method's tier weights, described by items and length.
• methods[].parameters[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the setting's value. (convention native_unit)
• methods[].parameters[].default (number / boolean / string / list; may be null; unit: the unit of what it describes) — The value the app uses when the setting is not given — a list of numbers for a list setting, the value of each item for a setting with a per — or null when the setting has none and must be chosen, such as a reference instrument. (convention native_unit)
• methods[].parameters[].min (number; may be null; unit: the unit of what it describes) — The smallest value allowed, or null when the setting is not a number. (convention native_unit)
• methods[].parameters[].max (number; may be null; unit: the unit of what it describes) — The largest value allowed, or null when the setting is not a number. (convention native_unit)
• methods[].parameters[].values (list; may be null) — The allowed values of an enum setting, or null for any other type.
• methods[].parameters[].steps (list; may be null; unit: the unit of what it describes) — The only numbers the setting accepts, ascending; null when any number between min and max is accepted. (convention native_unit)
• methods[].parameters[].boundsBy (object; may be null) — Bounds that depend on another setting of the method, one case per value of that setting; null when the bounds are fixed. The setting's own default, min and max are those of the other setting's default value.
• methods[].parameters[].boundsBy.on (string) — The name of the setting whose value decides the bounds.
• methods[].parameters[].boundsBy.cases (list) — One entry per value of that setting.
• methods[].parameters[].boundsBy.cases[].when (string; at least 1 characters) — The value of the deciding setting this case applies to.
• methods[].parameters[].boundsBy.cases[].unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of the setting's value in this case. (convention native_unit)
• methods[].parameters[].boundsBy.cases[].default (number / boolean / string; may be null; unit: the unit of what it describes) — The default in this case. (convention native_unit)
• methods[].parameters[].boundsBy.cases[].min (number; may be null; unit: the unit of what it describes) — The smallest value allowed in this case, or null. (convention native_unit)
• methods[].parameters[].boundsBy.cases[].max (number; may be null; unit: the unit of what it describes) — The largest value allowed in this case, or null. (convention native_unit)
• methods[].parameters[].boundsBy.cases[].steps (list; may be null; unit: the unit of what it describes) — The only numbers accepted in this case, ascending; null when any number between this case's min and max is accepted. (convention native_unit)
• methods[].parameters[].valuePlans (list; may be null) — The allowed values that need a higher plan than the setting itself; null when every value comes with the setting.
• methods[].parameters[].valuePlans[].value (string; at least 1 characters) — One of the setting's values.
• methods[].parameters[].valuePlans[].includedInYourPlan (boolean) — True when your current plan includes this value.
• methods[].parameters[].valuePlans[].lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that includes this value, or null when no plan includes it today.
• methods[].parameters[].items (object; may be null) — For a list setting, what each element is; null for any other type.
• methods[].parameters[].items.type (string; one of number, integer) — number or integer.
• methods[].parameters[].items.unit (string; one of none, number, count, days, weeks, months, quarters, years, reports, bars, fraction, percent, multiple, sharpe_points, sigma, usd, base_currency, date, native) — The unit of each element. (convention native_unit)
• methods[].parameters[].items.min (number; may be null; unit: the unit of what it describes) — The smallest value an element may take, or null. (convention native_unit)
• methods[].parameters[].items.max (number; may be null; unit: the unit of what it describes) — The largest value an element may take, or null. (convention native_unit)
• methods[].parameters[].length (object; may be null) — For a list setting, how many elements it holds; null for any other type.
• methods[].parameters[].length.min (integer; at least 0; unit: a count) — The fewest elements allowed.
• methods[].parameters[].length.max (integer; greater than 0; unit: a count) — The most elements allowed.
• methods[].parameters[].per (string; one of instrument, model, rank; may be null) — For a setting kept once per item, what it is kept per; null for a single value. instrument: send a map from each instrument's permaTicker to its value, such as a fixed weight inside a strategy. model: send a list with one value per strategy, in the order of models[], such as a fixed weight across a Combined, or each strategy's rotate switch and staticWeight in the ranking method. rank: send a list with one value per rank, best first, as many as the strategies whose rotate is on, such as rankWeight. type, unit, default, min and max then describe one value.
• methods[].parameters[].lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that allows the setting at these levels, which can be higher than the method's own; null when no plan allows it today.
• methods[].availability (object) — Whether your plan includes the method, level by level.
• methods[].availability.portfolio (object; may be null) — Availability at the Combined level, or null when the method does not work at that level.
• methods[].availability.portfolio.includedInYourPlan (boolean) — True when your current plan includes the method at the Combined level.
• methods[].availability.portfolio.lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that includes the method at the Combined level, or null when no plan includes it today.
• methods[].availability.model (object; may be null) — Availability at the strategy level, or null when the method does not work at that level.
• methods[].availability.model.includedInYourPlan (boolean) — True when your current plan includes the method at the strategy level.
• methods[].availability.model.lowestPlan (string; one of free, starter, advanced, ultimate, professional; may be null) — The lowest plan that includes the method at the strategy level, or null when no plan includes it today.
• methods[].operationId (string; may be null) — The operation that runs the method on its own, on any instruments, or null while that operation is not available yet.
• count (integer; at least 0; unit: a count) — How many methods matched.

What does a call to List allocation methods look like?

The inverse volatility method, and whether your plan includes it

Asked as: What can I tune in inverse volatility, and is it on my plan?

# Caller on the starter plan
POST /api/v1/research/list_allocation_methods
Authorization: Bearer <API key or access token>
Content-Type: application/json

{
  "query": "inverse volatility"
}

The result:

{
  "methods": [
    {
      "id": "inverse_volatility",
      "name": "Inverse volatility",
      "description": "Less-volatile instruments receive higher weights",
      "levels": [
        "portfolio",
        "model"
      ],
      "parameters": [
        {
          "name": "riskMeasure",
          "label": "Risk measure",
          "levels": [
            "portfolio",
            "model"
          ],
          "type": "enum",
          "unit": "none",
          "default": "annualized_volatility",
          "min": null,
          "max": null,
          "values": [
            "annualized_volatility",
            "max_drawdown"
          ],
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "items": null,
          "length": null,
          "per": null,
          "lowestPlan": "starter"
        },
        {
          "name": "allowShort",
          "label": "Direction",
          "levels": [
            "model"
          ],
          "type": "boolean",
          "unit": "none",
          "default": false,
          "min": null,
          "max": null,
          "values": null,
          "steps": null,
          "boundsBy": null,
          "valuePlans": null,
          "items": null,
          "length": null,
          "per": null,
          "lowestPlan": "starter"
        }
      ],
      "availability": {
        "portfolio": {
          "includedInYourPlan": true,
          "lowestPlan": "starter"
        },
        "model": {
          "includedInYourPlan": true,
          "lowestPlan": "starter"
        }
      },
      "operationId": null
    }
  ],
  "count": 1
}

The summary it returns:

1 allocation method matches 'inverse volatility': Inverse volatility, at the Combined level and the strategy level, included in your plan.

The values it assumed, because the request left them out:

• /level = "both" — no level was given, so the methods of both levels are listed

What goes wrong most often with List allocation methods?

• Black-Litterman is listed as its own method but runs on the mean-variance framework: its settings are the mean-variance settings plus its views.
• A method can work at one level and not the other, or be in your plan at one level only; read availability per level before building.
• Settings every method shares — the lookback, leverage, the covariance estimator where a method uses one — are not in parameters; describe_portfolio_model lists them.
• A setting can appear twice under the same name, once per level, when its bounds, values or plan differ between the levels; use the entry whose levels holds the level you are building.
• A setting can need a higher plan than its method, such as the Resampled switch of MPT (Markowitz); read each parameter's lowestPlan, not only the method's availability.
• A setting with a per is sent once per item, not once: fixed weights as a map by permaTicker inside a strategy or a list in strategy order across a Combined; in the ranking method across a Combined, a rotate switch and a staticWeight per strategy and a rankWeight per rank, one for each strategy that rotates.

Which error codes can List allocation methods return?

List allocation methods has no error codes of its own beyond the common ones.

Every operation can also return the common error codes listed in the reference.

Which plans include List allocation methods?

List allocation methods belongs to the Strategy authoring family of operations and counts as one research call against your plan's monthly allowance. Which families your plan includes, and how large its allowances are, is set out in What each plan includes.