# Read an account's Overview
Source: https://docs.tilt.now/advisor/account-overview

What each section of a client account's Overview shows and where its numbers come from.

An account opens on its **Overview**: how the account has performed and where it stands against its model, with its gains, its mix and its latest transactions beside them. Nothing on the page changes the account. Each section links to the tab that has the detail, such as **Open Optimization** or **Open Holdings**.

To open it, click **Clients**, open the client, and select the account by name.

The main column holds **Performance** and drift against the model. The side column holds **Gains**, **Allocation by asset class** and **Recent transactions**. When the page is too narrow for both, the side column moves below the main one.

| Section | What it shows | Where the numbers come from |
| - | - | - |
| **Performance** | The account's value and its return over a period, next to its model and measurement benchmark. | Tilt's daily values for the account. [Account performance](/advisor/account-performance) covers this section. |
| **Against** *model name* | Total drift, the largest sleeve drift, off-model weight, sleeves over a limit, and each top-level sleeve's drift. | The latest nightly drift check. |
| **Gains** | Unrealized short-term, long-term and total gain, and the gains realized in this account this year. | The account's tax lots at the latest close, the same figures as the **Holdings** tab, and the realized gains your firm enters. |
| **Allocation by asset class** | The account's weight in each asset class, now and in its target. | The latest nightly drift check. |
| **Recent transactions** | The three newest transactions. | The linked brokerage account. |

## Drift against the model

The section is titled **Against** and the model's name, with an **Open Optimization** button that opens the account's **Optimization** tab. When nothing is past a limit or a warning, a sentence says so, such as **Total drift and every sleeve are within their limits.**

| Tile | Meaning |
| - | - |
| **Total drift** | How far the account's holdings are from the model's targets. The caption shows the limit and the warning level. |
| **Largest sleeve drift** | The top-level sleeve furthest from its target, named in the caption. |
| **Off-model weight** | The share of the account in holdings the model doesn't include. These count toward total drift, not toward any sleeve's tracking error. |
| **Sleeves over a limit** | How many sleeves are past their drift limit, out of the model's sleeves, and how many are past a warning. |

The table below the tiles lists each top-level sleeve with its **Target**, **Current** weight and **Drift**, and, when the account's tracking-error check is on, its **Tracking error**. A sleeve past a warning or a limit has a badge under its figure. A sleeve within its limits has none.

Sleeves inside a composite, and Tilts set on a sleeve, appear only when they are past a warning or a limit or the check couldn't measure them. A line under the table counts the rest, and the **Optimization** tab lists every sleeve with its limits and the dates of the check. [Models and benchmarks](/advisor/models-and-benchmarks#where-a-tilts-tickers-count) explains how those rows are built.

![Against Global 80/20 section with an Open Optimization button and tiles for Total drift 6.60% (limit 6.00%, warns at 3.00%), Largest sleeve drift 6.60% in Fixed Income, Off-model weight 0.00% in 0 holdings, and Sleeves over a limit 1 of 13 sleeves. Below, a table of US Equity, International Equity and Fixed Income with target, current and drift; Fixed Income shows +6.60% with an Over limit badge. Notes underneath read 10 more sub-sleeves are on the Optimization tab, and The tracking-error check is off for this account.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/account-overview-drift.jpg?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=50680a822eabcd9b013f1f995bc7b195)

A Roth IRA against its model, Global 80/20. Fixed Income is over its sleeve drift limit, and the tracking-error check is off.

The check runs nightly, so a change to the model or the account shows up after the next check. If you move the account to another model, the section keeps the old model's name until then and says so.

An account without a model shows **Assign a model in Setup to see drift and compare performance with it.** with an **Open Setup** button.

## Gains

The table lists the account's **Unrealized short-term**, **Unrealized long-term** and **Unrealized total** gain at the latest close, and **Realized this year**: the gains entered for this account alone. A line below says how much of the client's capital gains budget is left. **Open Holdings** opens the **Holdings** tab, where the budget and realized gains are entered.

![Gains section with an Open Holdings button and a table of Unrealized short-term \$1,157, Unrealized long-term \$56,792, Unrealized total \$57,949 and Realized this year \$8,520. Below, the line \$16,480 of the \$25,000 budget for 2026 is left.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/account-overview-gains.jpg?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=b966c8e5ee3920f77661625f9b6af694)

A taxable brokerage account's Gains, with $16,480 of a $25,000 budget left for 2026.

When a lot has no latest price, a line says how many, and the unrealized gains that include them aren't shown. When the realized records are incomplete, **Realized this year** reads **Unknown**.

## Realized gains and the capital gains budget

A capital gains budget is the net capital gains a client's accounts may realize in a year. On the **Holdings** tab, **Realized gains this year** sets the budget and records the gains. Click **Set budget** to set it on the client's household, which covers every member without a budget of their own, or on the client alone. Tax-sheltered accounts don't count toward it.

The tiles show the **Budget**, the **Realized** total so far this year across the accounts it covers, and what's **Remaining**. A line below lists the accounts that count toward the budget.

![Realized gains this year section with a Within budget badge and the text \$16,480 of the \$25,000 budget for 2026 is left, buttons for Set budget, Add realized gains and Confirm records, and tiles for Budget \$25,000 set on this client, Realized \$8,520 (short-term \$2,140, long-term \$6,380) and Remaining \$16,480. Below, Counts toward it: Wei Chen Roth IRA, Chen Household IRA and Wei Chen Brokerage, then Realized in this account \$8,520, Opening amount for 2026 Entered, and Records complete through Oct 27.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/account-overview-realized-gains.jpg?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=147992a64f58a53c50808b8d84b6b65b)

The same account's Holdings tab, with the \$25,000 budget set on the client.

Tilt doesn't read realized gains from custodian activity. Your firm enters them for each account:

1. Click **Add realized gains**. The account's first entry for the year is its opening amount: the net short-term and long-term gains it realized from January 1 through a date you choose. Later entries add the gains realized on a date. Enter a loss as a negative amount, and note where the figures came from, such as a custodian report.
2. Click **Confirm records** and enter the date the account's records are complete through, with a note on how you checked.

Until every counted account has an opening amount and a current confirmation, **Realized** and **Remaining** read **Unknown** and the section says what's missing. They never show \$0 in place of a missing figure. Under the tiles, the open account shows its own realized amount, whether its opening amount is entered, and the date its records are complete through.

## Allocation by asset class

The table lists each asset class's **Target**, **Current** weight, and the **Difference** between them. The target is the portfolio the latest nightly drift check proposed for the account, which follows the model and the account's own settings. If that proposal didn't save, the section has no target to compare with.

A fund that holds more than one asset class counts toward each. **Cash** includes cash balances and holdings classified as cash. **Unclassified** includes funds and other holdings Tilt has no asset-class data for, and assets Tilt can't trade. A stock without asset-class data counts as equity.

## Recent transactions

The table lists the three newest transactions with their **Date**, **Transaction** (the type and ticker) and **Amount**, as the account's brokerage sent them. A line underneath names the brokerage and when Tilt last read it. **Open History** opens the account's full history. An account with no transactions to show has no **Recent transactions** section.

## Ask Tilt Agent

Open **Chat** and name the account, for example:

> Why is Maya Patel's Revocable Trust over its drift limit, and which sleeves are furthest from target?


# See how an account or household actually performed
Source: https://docs.tilt.now/advisor/account-performance

Compare what a client account or household really earned with its model and its measurement benchmark, and read what each line leaves out.

The **Performance** section at the top of an account's or a household's **Overview** shows what it actually earned over a period, next to its model and its measurement benchmark. The account's line comes from Tilt's daily values for the account and leaves deposits, withdrawals and transfers out of the return, so it shows how the invested money did. The screenshots use the made-up Northwind Family Office practice.

A backtest answers a different question: what a strategy would have done from cash. [Reports and backtests](/advisor/reports-and-backtests) covers it.

## Read an account's performance

Open the client, select the account, and stay on **Overview**. **Performance** comes first.

![Performance section showing Account value \$205,205, Account return 2.54%, Model return 2.70% and Benchmark return 3.18%, and a chart from Oct 28, 2025 to Oct 28, 2026 with lines for This account, Global 80/20 and a dashed 70/30 Stock and Bond Blend. A 1 year period menu sits at the end of the legend, under the chart.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/northwind-account-performance.png?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=3048654ccf5e269396b5ce45cedadfe1)

A Roth IRA over 1 year, against its model, Global 80/20, and its own measurement benchmark.

| Part | What it shows |
| - | - |
| **Account value** | The account's value at the chart's last close. Hover over it for the date. |
| **Account return**, **Model return**, **Benchmark return** | Each line's total return over the period. Hover over **Model return** or **Benchmark return** for the model's or the benchmark's name. |
| Chart | Growth of 100 from the period's first close. **This account** is drawn on top, the model is the solid line, and the benchmark is the dashed line. The legend names the model and the benchmark. |
| Period menu | Under the chart, at the end of the legend. **1 month** to **5 years**. The section opens on **1 year**. A period counts back from the latest market close every line has a value for, as on the model page. |

To change the measurement benchmark, open the account's **Setup** tab.

When the account's daily values begin after the period's start, the chart starts at its first value and a caption says **Since** that date. A model or benchmark line that can't be drawn for the period is left off the chart, with a sentence saying why, such as a missing price.

## How each line is measured

**Calculation assumptions**, below the chart, says how the lines are worked out.

| Line | How Tilt measures it |
| - | - |
| **This account** | The account's daily values, with money moved in or out left out: deposits, withdrawals, cash and share journals, and transfers. Tilt links each day's return to the next, so the return is time weighted. It is after fees and trading costs. |
| Model | The model the account follows today, holding its current targets from the period's first close with no rebalancing. It leaves out the account's own settings, such as a sleeve it holds differently, and is before fees and trading costs. This is the same calculation as the model page's **Historical performance**. |
| Benchmark | The account's own measurement benchmark, or its model's when the account has none. An index uses its published total-return levels. An ETF or a custom basket is bought at the first close and held. It is before fees and trading costs. |

![Calculation assumptions text: the account's return comes from its daily values with deposits, withdrawals, journals and transfers left out, and is time weighted; each close uses the last value recorded before the next market open; history starts when the account was linked to its current brokerage; the model line holds the model's current targets without rebalancing and leaves out this account's own settings; the benchmark is the account's own or its model's; both lines come from Tilt's backtest, except an index benchmark; the account's return is after fees and trading costs, and the model and benchmark lines are before them.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/northwind-account-calculation-assumptions.png?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=bf39e717733bac2ca4005f5d23b5cb03)

The account's Calculation assumptions, opened below the chart.

Keep these limits in mind when you compare the lines:

* The model line shows what today's targets would have done. It doesn't show what the account was told to hold at the time, and a model change during the period doesn't appear.
* The gap between the account and the model also reflects the account's fees and trading costs and anything it held differently from the model's targets.
* History starts when the account was linked to its current brokerage. A relinked account starts again from the new link.

[Models, sleeves, and benchmarks](/advisor/models-and-benchmarks#measurement-benchmark) explains where the measurement benchmark comes from.

## When an account has no return

Tilt shows no figures, and a sentence in place of the chart, when it has no daily values for the account or can't tell the account's gains from money moved in or out:

| Message | What it means |
| - | - |
| There are no daily values for this account. | Tilt measures accounts linked to a brokerage or custodian account, and records each linked account's value daily. The return shows once the account is linked and there are values to compare. |
| *Brokerage* doesn't send deposits and withdrawals to Tilt, so this account's return can't be measured. | Nothing in Tilt changes this. Some brokerages, such as Charles Schwab, don't send money moves to Tilt, so every deposit would read as a gain. |
| Tilt hasn't read this account's transactions yet, so its return can't be measured. | The return shows once Tilt has read the account's transactions from its brokerage. |
| Tilt's record of this account's deposits and withdrawals is incomplete, so its return can't be measured. | Nothing in Tilt changes this. Some brokerages leave deposits and withdrawals out of what they send Tilt, such as Interactive Brokers, or Wealthsimple when it reports a transfer without an amount, so a missing deposit would read as a gain. |
| *Brokerage* reported a transfer on *date* that Tilt can't value yet, so this account's return for this period can't be measured. | Some brokerages report journals and transfers between accounts in a form Tilt can't value as money in or out. |

## Read a household's performance

Open the household. **Performance** comes first on **Overview**, above its members and accounts.

![Household Performance section showing Household return 1.87%, Models return 2.89% and Benchmarks return 3.18%, and a chart from Oct 28, 2025 to Oct 28, 2026 with Household, Models (blended) and a dashed Benchmarks (blended) line. A 1 year period menu sits at the end of the legend.](https://mintcdn.com/tilt/ixw_hrwCqdwWubln/images/advisor/northwind-household-performance.png?fit=max\&auto=format\&n=ixw_hrwCqdwWubln\&q=85\&s=4c4c6e0fc5bb02d2c1cd5e0c2eeab338)

A household of three accounts over 1 year. Every account has a model and a benchmark, so the blends cover the whole household.

| Line | How Tilt measures it |
| - | - |
| **Household** | The member accounts' daily values added up, with money moved in or out left out. Money moved between members cancels out. An account whose values start later counts its first value as money in. |
| **Models (blended)** | Each account's model line, weighted each day by the account's share of the value at the previous close. |
| **Benchmarks (blended)** | Each account's measurement benchmark line, or its model's, weighted the same way. |

A blend leaves out accounts with no model, or no benchmark, and spreads the weight over the rest. When it doesn't cover every account, a line names the accounts it leaves out and the share of the household's value it covers. Compare the household's return with a blend only when the blend covers all of it; otherwise compare the covered accounts on their own pages.

Other notes under the chart name:

* an account left out of the household's return and both blends, with its reason from [When an account has no return](#when-an-account-has-no-return), such as a brokerage that doesn't send deposits and withdrawals;
* an account whose values stopped before the chart's last close, with the date its value is carried forward from.

The household is its members today for the whole period, so an account that left the household during the period isn't in its return. The household's return is after fees and trading costs; the blends are before them.

A client outside any household has no household chart. Each of the client's account pages carries the comparison.

## Ask Tilt Agent

Tilt Agent reads the same figures the page shows. Ask, for example:

* **"How has my client Wei Chen's Roth IRA done over the last year compared with its model and benchmark?"**
* **"How has the Chen household done against its models and benchmarks over 3 months?"**

Tilt Agent gives the dates the figures cover, names the model and the benchmark, and says the account's return is after fees while the model's and the benchmark's are before them. When an account can't be measured, it gives the reason instead of a number. It doesn't run a backtest to answer these questions.

***

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. Account and household returns come from the values and money moves Tilt receives from each account's brokerage or custodian.


# Define and apply an account template
Source: https://docs.tilt.now/advisor/account-templates/manage

Save reusable settings in Firm Setup, then review and apply them to an account.

Firm owners and editors can create, edit, or archive templates. Applying a saved template requires account-edit permission and access to the account.

## 1. Create and save a template

1. Open **Firm > Setup > Account templates** and select **Create template**.
2. Name the template and describe its intended use. Optional intended account types guide selection; they do not assign the template to future accounts.
3. Use **Add setting** to include the settings to copy. For a setting that should return to inheritance, choose **Reset account setting**. For a model assignment, **Remove model assignment** removes the assignment rather than choosing an inherited model.
4. Select **Add to queue**, review the definition in **Queued changes**, then select **Apply firm changes** to save it. Saving the definition leaves accounts unchanged.

Leave out settings you do not want to copy. **Remove** omits a setting from future applications without clearing account values. See [Firm queue controls](/advisor/review-the-firm#setup) to undo or discard queued changes.

## 2. Review and apply it to an account

1. From any account tab, open the **…** menu in the account header and choose **Apply account template…**. Apply or discard queued **Setup** changes first, and wait for any save to finish.
2. Search by template name, description, or intended account type. Check the intended types, then select the template’s row to load the comparison for this account. A type mismatch warns but does not block application. The comparison excludes queued definition edits.
3. Review the before/after lines. Actual changes start checked; matching saved settings appear as **Unchanged**. Uncheck changes you do not want to apply.
4. Inspect list additions and removals and any changes to inheritance. Copying a value that matches an inherited value can still write an explicit account override.
5. Resolve incompatible selections, such as a model change that conflicts with a retained sleeve setting. Tilt refreshes the review when you change your selection. Review and reselect any lines whose effects changed.
6. Select **Apply changes** to save the checked changes. Applying a template does not place trades.

## 3. Edit or archive a template

Return to **Firm > Setup > Account templates**. Select **Edit**, change the settings, and select **Update queued template**. To retire a template, select **Archive** instead. Review **Queued changes** and select **Apply firm changes**.

Existing account settings stay unchanged. **Show archived** includes retired templates in the list; past application records remain available.

## Apply with Tilt Agent

Ask for a review using your saved template and account names:

> Prepare IRA standard for Jordan Lee Roth IRA. Keep its cash buffer unchanged. Show me the changes before applying.

Review the proposed changes before authorizing them. Tilt Agent can also prepare applications for several named accounts, with a separate setting selection for each.

See the [reference](/advisor/account-templates/reference) for supported settings, reset behavior, and validation.


# Account templates
Source: https://docs.tilt.now/advisor/account-templates/overview

Understand how reusable settings relate to accounts and shared models.

An account template is a saved set of settings you can copy into accounts during initial setup or later. For example, a cash-only template can set a standard cash buffer while leaving model assignments untouched.

## Copy settings into accounts

Saving a template defines the settings to copy. Applying it is a separate action: you review the proposed changes for an account and choose which to save. Application writes ordinary account settings, which you can edit afterward. It does not place trades.

A template includes only the settings you choose. Omitted settings stay untouched. For settings that support resets, a template can remove an account override and restore that setting's existing model or firm inheritance. Resetting a model assignment removes the assignment; it does not choose an inherited model.

Intended account types help you choose a template. They do not change account registration or create automatic assignments for future accounts.

## Keep templates separate from shared models

After application, the account has no ongoing connection to the template. Editing the template changes future applications; existing account settings stay as they are. Applying it again compares the revised instructions with the account's current settings.

A model assignment copied from a template still references the shared model. Later model edits can affect assigned accounts under the usual [shared-model behavior](/advisor/models-and-benchmarks). Editing the template does not edit the model's allocation.

See [Define and apply an account template](/advisor/account-templates/manage) for the workflow, or the [reference](/advisor/account-templates/reference) for supported settings, permissions, and save behavior.


# Account-template reference
Source: https://docs.tilt.now/advisor/account-templates/reference

Look up supported settings, copy semantics, permissions, and save behavior.

## Template contents

| Family | Reusable contents |
| - | - |
| Model and sleeves | Shared model assignment and applicable sleeve implementation or customization choices. |
| Cash | Cash buffers and reserve amounts. |
| Tax | Tax rates, tax-loss harvesting settings, and account optimizer tax budgets or gain targets. |
| Trading and optimization | Trading controls, turnover limits, risk limits, and optimization settings. |
| Restrictions and exposures | Restrictions, exposure bounds, substitutions, and exemptions with required reasons. |
| Conditional rules and monitoring | Account-scoped rules and monitoring-policy configuration. |

Templates exclude account identity, registration, holdings, balances, and realized history. Shared annual capital-gains budgets belong to the client or household and remain separate from account optimizer tax settings.

Defining or applying a template does not grant trading authority, activate management, place trades, or start scheduled work.

## Field instructions

| Instruction | Effect when selected for application |
| - | - |
| Not included | Leave the account setting untouched. |
| Set a value | Replace the account's saved value. |
| Reset account setting | Clear the account-specific value using that setting's reset behavior, including model or firm inheritance where applicable. |
| Remove | Omit the field from future applications; preserve existing account values and past records. |

Omission and reset are distinct instructions. Zero, false, and empty selections remain deliberate values where supported.

Copying a list replaces the account-level list; the review shows additions and removals. Inherited model and firm restrictions, resolution rules, and required exemption reasons still apply.

## Models and saved values

| Case | Result |
| - | - |
| Included model assignment | Reference the shared model without duplicating its allocation. Later model edits retain normal shared-model behavior. |
| **Remove model assignment** | Remove the account's model assignment without choosing an inherited model. Omitting the setting leaves its assignment untouched. |
| Template value matches saved configuration | Show **Unchanged**, outside selectable changes. |
| Template value matches an inherited effective value | Show a configuration change if copying writes an explicit account override. |

When creating a template from an account, Tilt Agent copies requested effective scalar values and preserves shared model references. The source account has no ongoing connection to the template.

For monitoring, Tilt Agent copies only an explicit account policy, preserving inherited layers. A source with no explicit policy requires a chosen policy or reset instruction. Conditional rules can fall through to different inherited policies at the destination, so the effective monitoring outcome can differ.

## Selection and validation

| Situation | Behavior |
| - | - |
| Open an application review | Check all proposed changes by default. |
| Uncheck a setting | Preserve its current configuration. |
| No checked changes for an account | Make no changes to that account. |
| Repeat an application | Compare current template instructions with current account settings. Selected copies can overwrite later account edits. |
| Selected model conflicts with a retained sleeve setting | Require a compatible selection; preserve unchecked settings. |
| Selected account configuration is invalid | Save none of the selected batch. |
| Relevant state changes during review | Require renewed review of changed lines; preserve selections for identical changes. |

Application uses saved template definitions, excluding queued edits. Tilt Agent supports several accounts with a separate setting selection for each. Tilt saves all selected account changes together or saves none; this guarantee covers Tilt configuration, not custodian operations.

The Firm queue can partially succeed: successful saves leave the queue and failed changes remain. Saving definitions leaves accounts unchanged. See [Firm queue controls](/advisor/review-the-firm#setup).

## Template lifecycle

| Action or state | Effect |
| - | - |
| Edit a template | Change future applications; preserve existing account settings. |
| Archive a template | Prevent new applications; preserve account settings and past records. |
| Intended account type mismatch | Warn without changing registration or blocking application. Intended types create no automatic assignment rule for new accounts. |
| Saved definition changes during editing | Block the stale draft from overwriting it. **Discard edits and reload saved templates** clears template drafts and reloads saved definitions. |

## Permissions and records

| Action | Required permission |
| - | - |
| Create, edit, or archive a definition | Firm owner or editor. |
| Apply a saved template | Account-edit permission and access to the account. |

The app and Tilt Agent enforce the same permissions.

| Record | Preserved information |
| - | - |
| Definition creation, edit, or archival | Actor, time, action, and definition changes, including previous contents. |
| Application | Template identity and contents used, actor, time, account selection, selected before/after changes, and each account's result. |

Records survive later template edits and archival.

See [Account templates](/advisor/account-templates/overview) for the copy model, or [Define and apply](/advisor/account-templates/manage) for instructions.


# Work with your advisor book in chat
Source: https://docs.tilt.now/advisor/advisor-chats

Organize advisor chats, prepare client reviews, and repeat useful work with Tilt Agent.

Use Tilt Agent to investigate a question across your book, prepare for a client meeting, or repeat a review. For model portfolios, account setup, optimization, and proposal decisions, start with the [Advisor workflows](/advisor/overview).

## Before you start

Open **Settings > Guidance Packs** and install **Advisor**. Choose the advisor organization you want to work in. The results depend on the clients, accounts, holdings, portfolios, and reports available to that organization. Ask Tilt Agent to name missing or stale data.

## Organize chats around the work

Start in your Main chat for day-to-day requests across your book. You can move between clients and accounts without starting a new conversation. Name the client and account you mean, and check [**Looking at**](/tilt-agent/ask-about-page) when asking about an open page.

Use another chat when a client review or other assignment needs its own ongoing conversation. You can ask Tilt Agent to handle that work in another chat while you continue in Main chat. Tilt Agent looks for an existing chat before creating one. It names client chats `<client> — <decision or review>`.

The first time Tilt Agent plans to use another chat for a different client, an unrelated decision, or a book review, it asks how you want your chats organized:

| Preference | What Tilt Agent does |
| - | - |
| **Organize automatically** | Uses another chat for a different client, unrelated decision, or book review without asking each time. |
| **Designated main chat** | Keeps your requests in one main chat and sends separate work to other chats. |
| **Keep work here** | Keeps advisor work in the current chat. |
| **Ask each time** | Asks before using another chat. |

Choose **Designated main chat** to keep bringing requests to one place while Tilt Agent sends separate work to other chats.

Tilt Agent saves your choice and uses it for future advisor work. The choice only affects whether Tilt Agent uses another chat. Tilt Agent still asks before financial actions, deleting a chat, or other changes that need your approval. Asking it to use another chat once does not change your saved choice.

When Tilt Agent asks another chat to handle part of your request, the current chat shows **Message sent to** and the receiving chat shows **Message from**. Select the chat name to move between them. **Message sent to** confirms that Tilt Agent sent the request. Open the receiving chat to see whether the work is complete.

![Two Tilt Agent chat states showing Message sent to Taylor Morgan — review in Daily book review and Message from Daily book review in Taylor Morgan — review](https://mintcdn.com/tilt/XsVxqz_G2m1P4TAl/images/tilt-agent/coordinated-advisor-chats.png?fit=max\&auto=format\&n=XsVxqz_G2m1P4TAl\&q=85\&s=40c79df68d311a40f31960d23fe0e66c)

The sending and receiving chats link to each other.

Name the client and account in your request. If you do not know the exact record, ask Tilt Agent to list clients and accounts in the selected advisor organization. If a name matches more than one record, choose the intended one before continuing. Before relying on findings from an older or different chat, ask Tilt Agent to refresh the holdings, balances, proposals, configuration, and account state in Tilt.

## Triage the book

Ask Tilt Agent for your advisor daily briefing in Main chat. You can also choose **Daily briefing** in a book-wide review chat. If you chose **Organize automatically** or **Designated main chat**, you can ask Tilt Agent to run the briefing in another chat. Tilt Agent uses today's completed advisor report or starts today's calculation. [Read the Daily briefing](/advisor/daily-briefing) to understand its coverage, breaches, and attention accounts before investigating an exception.

Ask a follow-up in the same chat:

```text theme={null}
Which accounts need my
decision first today?
Show three. For each:
- client and account
- dated evidence
- decision needed
- missing data
```

If today's briefing is still being calculated, return to it before treating older results as current.

## Prepare a client review

In any chat, give Tilt Agent the client and account you mean. Tilt Agent follows your saved choice: it keeps the work in the current chat, creates or reuses a chat for that client, or asks before using another chat.

```text theme={null}
Prepare a review for
[client] and [account].
Show:
- holdings date
- assigned portfolio
- allocation drift and cash
- pending or completed
  proposals
Separate facts from
questions for the client.
End with my decisions.
Flag unverified facts.
```

Use the answer as a working brief. Add the client's goals or meeting notes if you want Tilt Agent to consider them; ask it to distinguish those inputs from account data in Tilt. Continue in the same chat to examine a surprising holding, compare the account with its target, or revise the brief. After the meeting, provide your notes and ask for a draft recap and follow-ups to review.

If the review leads to a rebalance, [review the account and its proposal](/advisor/review-rebalance) before any trade decision.

## Repeat a useful review

Ask Tilt Agent to repeat a review on a schedule when you want ongoing coverage. Specify the organization, scope, time zone, and when it should post a result. [Create an automation in chat](/tilt-agent/create-automation), then use **Run now** in **Automations** to inspect a representative result and edit the assignment before relying on future runs.

If you use a review format repeatedly, ask Tilt Agent to [turn it into a Personal Skill](/tilt-agent/create-personal-skill). Keep the client's current facts in the chat; use the skill for the questions, structure, and safeguards you want to reuse.

## Open advisor dashboards

Ask Tilt Agent to open the **Advisor Dashboard** to inspect practice holdings, exposure, and the latest saved book report. **Client Portfolio** shows the advised accounts shared by linked client households; a client appears after their household grants access and connects a brokerage. These dashboards stay in **Library > Dashboards**; **Advisor Dashboard** is also listed there as a starter until you open it. Select **Reload** to run a dashboard again. Use **Daily briefing** for today's book review; the dashboards do not save the preceding chat review.


# Build a model portfolio
Source: https://docs.tilt.now/advisor/build-model-portfolio

Define sleeve targets, create and change shared composites, review the accounts a model affects, and assign it to client accounts.

Build a model portfolio when several accounts should share a target allocation. A sleeve represents one part of that allocation, such as US large-cap equity or international bonds. A composite sleeve holds other sleeves. The screenshots show the **Global 80/20** model in the made-up Northwind Family Office practice.

## 1. Open or create a model

Open **Models** in the sidebar. The table compares your models: each **Composition** bar sizes a model's top-level sleeves by weight, with a thinner tier for what its composites hold. **Configurations** summarizes how the model's accounts differ from it; [Compare a model's account configurations](/advisor/compare-account-configurations) explains that column.

![Models table with Model, Composition, Sleeves, Accounts, Configurations, and AUM columns. Global 80/20 shows 3 sleeves, 9 accounts, 5 configurations, and \$6,128,000.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-models-index.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=5adb92e47c8dfb1ebabb1be194587969)

The Models table. Global 80/20 has 9 accounts in 5 configurations; the other models' accounts all follow their models.

Select a model to review it, or choose **Create model** to name a new one. A newly created model needs sleeves and target weights before an assigned account can use it for optimization.

You can also ask Tilt Agent to propose a model or a composite sleeve. Describe the exposures and target weights you want, then ask it to show the complete allocation before saving. Review sleeve membership and the targets inside each composite before confirming the proposal.

## 2. Set the allocation

**Allocation** shows the model as an indented tree. Each composite expands to the sleeves it holds; use **Expand all** and **Collapse all** to change how much of the tree shows. **Target %** is a sleeve's share of the sleeve that holds it, and **Model %** is its share of the whole model. **Used by** counts the models that hold each sleeve and the accounts on them.

![Allocation tree for Global 80/20 with Sleeve, Target %, Model %, Used by, and Customized in columns. US Equity has a 50 target field; US Large Cap shows 70% and 35%; US Large Growth (IUSG) shows 55%, 19.3%, and 4 accounts.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-model-allocation.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=4e65fd9fe037eb778849be3a414e91dc)

Global 80/20's Allocation. US Equity holds US Large Cap, which holds US Large Growth and US Large Value. The model's own targets are editable fields.

Type a target for each of the model's top-level sleeves. Select **Add sleeve** to add a sleeve from your organization, including a composite. A sleeve joins at 0%; enter its target and adjust the others so the total reaches 100%. Tilt keeps allocation edits in the change queue and requires a complete allocation before you can apply them.

Each row's actions menu groups its changes by what they affect:

| Menu group | Action | What it changes |
| - | - | - |
| **In this model** | **Tilts and direct indexing…** | How this model manages one of its top-level sleeves |
| **In this model** | **Remove from model** | This model's allocation |
| **In** the composite that holds the sleeve | **Tilts and direct indexing…** | What that composite gives the sleeve, for every model that holds the composite |
| **Shared sleeve** | **Edit …** | Opens a composite to change what it holds, for every model that holds it |

![Actions menu for US Large Cap with an In US Equity, Shared sleeve, 2 models group listing Tilts and direct indexing, and a Shared sleeve, 4 models group listing Edit US Large Cap.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-allocation-row-menu.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=1cf6ac5eb875b4d671d108378c05f5f8)

US Large Cap's actions menu. US Large Cap sits inside US Equity, which 2 models hold, and 4 models hold US Large Cap itself.

Review the benchmark, Tilts, and direct indexing choices before queueing a change. The sleeve's target weight sets its share of the model; its implementation settings determine how an account can reach that exposure.

### Set the direct-indexing default for a reusable sleeve

Open **Sleeves** beside **Models**, select an eligible building-block sleeve, and find **Default direct indexing** under **Definition**. Set the switch, review **Queued changes**, and select **Apply** to save the default.

![Definition table for US Large Growth (IUSG): Holds ETF or index: iShares Core S\&P U.S. Growth ETF, Default direct indexing switched on with the note Default for new placements. Existing placements aren't changed, and Alternative ETFs None.](https://mintcdn.com/tilt/qg2aU0WAFYJQ1YKN/images/advisor/northwind-default-direct-indexing.jpg?fit=max\&auto=format\&n=qg2aU0WAFYJQ1YKN\&q=85\&s=88fac5701fb524b2fb4045c56eb5a8bd)

US Large Growth with Default direct indexing turned on, waiting in the queue.

A custom-index sleeve is always direct indexed, so its **Definition** shows **Direct indexing** with no switch.

When you add that sleeve to a model or composite, its **Direct indexing** starts from the saved default. Where the switch is editable, you can turn it off for that placement before saving, even when the default is on. In a model, use the row's **Tilts and direct indexing…** action; inside a composite, use **Tilts…** on the child sleeve.

Changing the default leaves existing model and composite placements and account overrides unchanged. To change an existing placement, edit its own **Direct indexing** setting. The default sets a starting choice; it does not require every use of the sleeve to stay direct indexed.

Changing what the sleeve holds to a single security, a security basket, or an ETF that can't be direct indexed turns the default off.

The placement pickers keep these always-on rules:

| Sleeve holds | Model picker | Composite picker |
| - | - | - |
| Custom index | Direct indexing always on | Direct indexing always on |
| Tilt | Direct indexing always on | Starts from the sleeve's default, where supported |

For a Tilt sleeve, **Default direct indexing** therefore controls new composite placements. Eligibility still depends on what the sleeve holds; see [direct-indexing support](#change-what-a-composite-holds).

Tilt Agent can set the default when it creates or changes a sleeve.

### Use a private Tilt in a sleeve

A private Tilt is one your firm built and hasn't published. You don't need to publish it to use it in a sleeve. In a sleeve's **Tilts** section, search under **Search tilts and indexes**: your firm's Tilts appear first under **Private**, and published Tilts and indexes under **Published**. With no search text, the list shows your firm's Tilts, newest first. Any advisor in the firm can add them.

![US Equities sleeve dialog with a target of 26% and no tilts yet. The Search tilts and indexes field holds robot, and its list shows Humanoid Robotics, a Tilt, under Private, then under Published the US All Cap Robotics Consensus TILT index, the Robots and Every Robot Needs Bearings Tilts, and indexes such as Manufacturing Machinery and Technology.](https://mintcdn.com/tilt/ZB2VP0uKN77kIvaA/images/advisor/private-tilt-picker.jpg?fit=max\&auto=format\&n=ZB2VP0uKN77kIvaA\&q=85\&s=037dc469fd51a040f68bc30d8703df2b)

Adding a tilt to the US Equities sleeve of Growth Portfolio in Demo Organization. A search for robot lists the firm's Humanoid Robotics under Private, above the published results.

A Tilt you add starts at **+10%**. Change the number in its row to set its weight. The weight is the share of the building block the Tilt's tickers take: at +10%, what the sleeve holds scales down to 90% and the Tilt's tickers fill the other 10%. [How a tilt changes a sleeve](/advisor/models-and-benchmarks#how-a-tilt-changes-a-sleeve) works through the arithmetic for composites and each kind of building block.

For a model mixing direct-indexed building blocks and ETFs, [compare parent and building-block placement](/advisor/models-and-benchmarks#compare-parent-and-building-block-placement) before choosing where to add the Tilt. Direct indexing off does not prevent a Tilt from introducing individual ticker targets.

A sleeve holds the Tilt itself, so editing a private Tilt changes the targets of every sleeve that holds it. Nothing trades until an advisor reviews and sends a proposal. [Working copies and published versions](/index-construction/working-copies-and-published-versions#use-a-working-copy-in-a-sleeve) explains which version of a Tilt a sleeve uses.

## 3. Create or change a shared composite

A composite belongs to your organization, so a change to it reaches every model that holds it and every account on those models.

### Create a composite

Open **Sleeves** beside **Models** and select **New sleeve**. Under **Holds**, choose **Sleeves**. Search for each sleeve the composite holds and type its share. A composite can hold building blocks and other composites. **Create sleeve** waits until the shares total 100%. While the **Composites** list is empty, its **New composite** opens the same form with **Sleeves** chosen.

![New sleeve dialog with the name US Small and Mid Cap, Holds set to Sleeves, US Mid Cap (VO) at 60 and US Small Cap (VB) at 40, a Search sleeves to add field, Total 100%, and a Create sleeve button.](https://mintcdn.com/tilt/9xzL1smQgfroOreu/images/advisor/northwind-composite-create.jpg?fit=max\&auto=format\&n=9xzL1smQgfroOreu\&q=85\&s=6847ea108f39dbca2c7ed52b47002ba4)

A new composite, US Small and Mid Cap, holding US Mid Cap at 60% and US Small Cap at 40%.

The new composite saves at once. No model holds it until you add it with a model's **Add sleeve**.

### Change what a composite holds

Select **Edit …** in the composite's actions menu, or open the composite from **Sleeves** and select **Holds**. Each sleeve the composite holds has its share of the composite and its own controls:

* Type a new share.
* Select **Tilts…** to set the tilts and direct indexing the composite gives that sleeve.
* Remove a sleeve to stop holding it. The tilts the composite gave it go with it.
* Search for a sleeve to add it at 0%.

**Queue changes** waits until the shares total 100%.

![What US Large Cap holds dialog with US Large Growth (IUSG) at 60 and the tilt Quality Leaders +5% beneath its name, US Large Value (IUSV) at 40, a Tilts button and a remove control on each row, a Search sleeves to add field, Total 100%, and a Queue changes button.](https://mintcdn.com/tilt/9xzL1smQgfroOreu/images/advisor/northwind-composite-holds.jpg?fit=max\&auto=format\&n=9xzL1smQgfroOreu\&q=85\&s=c697556a3eed8383bb880877a8b4e3bc)

US Large Cap's Holds, changed to 60/40 with Quality Leaders +5% on US Large Growth.

To set the tilts or direct indexing of a sleeve inside a composite from a model, select **Tilts and direct indexing…** in that sleeve's actions menu. The composite opens on that sleeve's settings. Direct indexing is available for a building block whose holding supplies its constituents. A custom index is always direct indexed. An ETF can be when its index supports it, and a Tilt when it supplies constituent weights; Tilt refuses the change otherwise. A composite or a security basket can't be direct indexed.

![What US Large Cap holds dialog showing US Large Growth (IUSG) in US Large Cap, with a Tilts section reading No tilts and a Search tilts and indexes field, a Direct indexing switch turned off, and Back and Done buttons.](https://mintcdn.com/tilt/9xzL1smQgfroOreu/images/advisor/northwind-composite-sleeve-settings.jpg?fit=max\&auto=format\&n=9xzL1smQgfroOreu\&q=85\&s=e37fd6c271dba7482a13830df5de8dc6)

The settings US Large Cap gives US Large Growth.

The change waits in the composite's **Queued changes**. Check the old and new holdings, then select **Apply**. The queue names how many models the change reaches. It also counts the accounts that set a sleeve you change differently from the model, since they keep their own settings. An account whose own setting matches the model today isn't counted.

![Queued changes panel with a Sleeve Holds change from US Large Growth (IUSG) 55%, US Large Value (IUSV) 45% to US Large Growth (IUSG) 60% with Quality Leaders +5%, US Large Value (IUSV) 40%, the note Applies to the 4 models that hold this sleeve. 4 accounts set US Large Growth (IUSG) differently from the model and keep their own settings, and Discard all and Apply 1 change buttons.](https://mintcdn.com/tilt/9xzL1smQgfroOreu/images/advisor/northwind-composite-queue.jpg?fit=max\&auto=format\&n=9xzL1smQgfroOreu\&q=85\&s=46ebd747f5d5a971d8ed978ccc788e87)

The queued change to US Large Cap. Four accounts set US Large Growth differently from the model and keep their settings.

The queue also tells you when the change affects accounts' own customizations: which ones move with their sleeve, which stop applying because their sleeve leaves the model, and which apply again. A customization that stops applying stays saved in the account.

![Queued changes panel for US SMID Cap Equity, changing US Small Cap 35% to US Small Value 35%, with the note 2 accounts' customizations of US Small Cap stop applying until US Small Cap is back in the model, and an Apply 1 change button.](https://mintcdn.com/tilt/F6YFsZbsydHw-1LM/images/advisor/cedar-composite-removal-impact.jpg?fit=max\&auto=format\&n=F6YFsZbsydHw-1LM\&q=85\&s=0c0b3fcadcc83221b82b5da5f76cc5b2)

Replacing US Small Cap with US Small Value in a shared composite, in the made-up Cedar Ridge Wealth practice. Two accounts had customized US Small Cap.

If a customized sleeve leaves its place and ends up in more than one place, Tilt can't tell which one the customization belongs to. The queue explains, and you can reset that customization or keep the sleeve in one place.

If someone else changes the composite while you edit it, Tilt asks you to reload it or keep editing. A composite keeps holding sleeves; to hold an ETF or a security directly, create another sleeve.

An [archived composite](/advisor/models-and-benchmarks#archived-sleeves-stay-in-the-models-that-hold-them) offers no **Edit …** action, and the sleeves inside it offer no **Tilts and direct indexing…**. Unarchive it first.

### Change what a building block holds

Open **Sleeves** beside **Models**, select the building block, and select **Holds**. Choose the kind of holding, select **Change**, and search for the new one. Every model that holds the sleeve follows the change once you apply it.

While a model, a composite, or an account direct indexes the building block, its new holding has to support direct indexing. Pick one that doesn't, such as a single security, a security basket, or an ETF whose index doesn't support it, and the dialog names each place where direct indexing is on. **Queue changes** stays off for that pick. Each account name opens that account's **Setup**.

![What the sleeve holds dialog for US Large Growth with ETF or index: SPYM, State Street SPDR Portfolio S\&P 500 ETF chosen. A warning reads SPYM can't be direct indexed. Direct indexing is on for this sleeve in 4 accounts: Chen Household IRA, Lindqvist Joint, Okafor Education Trust, and Okafor Family Trust, each name a link. Queue changes is unavailable.](https://mintcdn.com/tilt/j9D1HVGZiCH1BY6r/images/advisor/northwind-building-block-direct-indexing.jpg?fit=max\&auto=format\&n=j9D1HVGZiCH1BY6r\&q=85\&s=e8d6708819708e278891af7cc21f4f11)

US Large Growth can't hold SPYM while four accounts direct index it.

To change the holding for every model, first turn direct indexing off in each place the dialog names:

| Where direct indexing is on | Where to turn it off |
| - | - |
| A model | **Tilts and direct indexing…** under **In this model** in the sleeve's actions menu |
| A composite | **Tilts…** on the sleeve in the composite's **Holds** |
| An account | **Customize** on the sleeve in the account's **Setup** |

To change the holding for one account and keep the firm's sleeve as it is, use **Edit for this account…** in that account's **Setup**; see [Change what a sleeve holds](/advisor/tailor-account#change-what-a-sleeve-holds). Tilt Agent reads the same list: ask it to change the holding and it names what blocks the change.

## 4. Check the impact and save

Open **Accounts** to see which client accounts follow the model. Each account shows how many of the model's sleeves it customizes, or **Follows the model**.

![List of Global 80/20 accounts, such as Okafor Family Trust with 2 customized sleeves, Lindqvist Joint with 1 customized sleeve, and Ngozi Okafor Brokerage marked Follows the model.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-model-accounts.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=3f73cc5713106caed9133b889df4a325)

Global 80/20's Accounts. Six accounts customize one or two sleeves; three follow the model.

On **Setup**, review **Tax**, **Transactions**, **Optimization**, and **Constraints**. Model values apply to accounts that inherit them. Account overrides remain specific to their accounts.

Open **Queued changes** at the bottom of the model page. Check each old and new value and the number of accounts affected. When an allocation change moves, removes, or restores a sleeve that accounts customize, the queue says what happens to those customizations, as it does for a [shared composite](#change-what-a-composite-holds). Remove unwanted changes, choose **Discard all** to abandon the draft, or select **Apply** to save it. Reopen the model to check the saved allocation and settings.

## 5. Assign the model to accounts

On the model's **Accounts** view, select **Add accounts**. The dialog lists your organization's accounts that don't follow this model, grouped under their clients, with accounts that have no model first. Each row shows the model the account follows now, or **No model**, and how many sleeves the account customizes. Search by account or client name, select the accounts, and select **Add**.

![Add accounts to Global 80/20 dialog with a Search accounts or clients field and accounts grouped under Chidi Okafor, Erik Lindqvist, and Ngozi Okafor. Chidi Okafor Rollover IRA, on Growth Core, and Lindqvist Traditional IRA, on Global 60/40, are selected; Lindqvist Individual, on Income & Real Assets, is not. The button reads Add 2 accounts.](https://mintcdn.com/tilt/EY2DZ4hVyyqzcLrJ/images/advisor/northwind-add-accounts.jpg?fit=max\&auto=format\&n=EY2DZ4hVyyqzcLrJ\&q=85\&s=9b19f99571ea647834a68218abf051f4)

Adding accounts to Global 80/20. Two accounts on other models are selected.

An account on another model moves to this one as its primary model. An account using inherited allocation follows the new model's composition. An account with its own portfolio weights replaces the previous primary model at its existing weight and keeps its additional sleeves and their weights. If the new primary model is already an additional sleeve, Tilt combines those weights. Review the assignment warning for customizations that may stop applying. Select **Add** again to confirm when prompted, or **Back** to change the selection.

Tilt saves each account's model at once, outside the model's change queue, so **Add accounts** waits until you apply or discard the model's queued changes. If Tilt refuses an account, that account stays selected with the reason, and the other accounts keep the new model. You can't assign an archived model to more accounts.

To change one account's model, open the client from **Clients**, select the account, and open **Setup**. Choose **Assign model**, or **Change** beside the existing model, then select **Save**. The same warning appears before you save.

Check **Model**, **Portfolio**, and **Sleeves** in the account's saved setup. The primary model supplies inherited settings. The account can follow its allocation or set account-specific weights, such as 90% in the primary model and 10% in another sleeve. [Tailor the account](/advisor/tailor-account#set-account-portfolio-weights) for those weights, direct indexing, Tilts, tax settings, and restrictions, then [review a rebalance](/advisor/review-rebalance) when the saved inputs are ready.

For allocation mathematics, composites, and the difference between sleeves, implementations, and asset-class types, read [models and benchmarks](/advisor/models-and-benchmarks).


# Advisor changelog
Source: https://docs.tilt.now/advisor/changelog

New features, improvements, and fixes for advisors using Tilt.

**November 3, 2026**

## Improvements

* **Template settings:** Owners and editors can search settings grouped by task, with specialist controls inside the template editor. [Define a template](/advisor/account-templates/manage)
* **Template resets:** Distinct reset, remove-setting, and remove-model actions clarify which account values change when you apply a template. [Reset behavior](/advisor/account-templates/reference)
* **Large accounts:** Account reads reuse historical-volatility calculations for unchanged holdings, reducing repeated work when you or Tilt Agent review large accounts.
* **Saved ideas:** When building a Tilt, Tilt Agent saves its investment idea and the reasons behind its themes.
* **Long conversations:** Tilt Agent can summarize large, idle conversations before you return, reducing the history it must process on your next message.
* **Reply preparation:** Tilt Agent starts eligible follow-ups sooner and loads independent inputs together, reducing setup work before a response begins.

## Fixes

* **Template reviews:** Changing checked settings revalidates the selected combination and retained account settings before Apply becomes available. [Review changes](/advisor/account-templates/manage#2-review-and-apply-it-to-an-account)
* **View-only access:** Viewers retain firm reads and comparisons, while Tilt blocks business-setting changes through both the app and Tilt Agent.
* **Library counts:** Rules-based Tilts show ticker counts from their latest evaluation or published snapshot, rather than an incorrect zero.
* **Weight caps:** Tilt Agent enables requested single-position caps when constructing a basket and supplies a saved Rules link when you ask.
* **Unpublished backtests:** Backtests of unpublished rules-based Tilts use the latest loaded construction date, avoiding requests for data that has not arrived.
* **Sector filters:** Construction retains cached industry classifications when a month's source data is missing, preventing unrelated companies from losing their classifications.
* **Theme explanations:** Editing construction expressions removes reasons for discarded themes, while Tilt Agent leaves ambiguous theme directions unresolved.

**November 2, 2026**

## New

* **Firm monitoring:** Edit four watches in Firm Setup's Monitoring dialog, then review the queue and Apply firm changes to save. [Monitoring policies](/advisor/monitoring-policies)
* **Background file reads:** With Tilt for Mac 1.34.1 open, approve a background job's local CSV request in the file chooser.

## Improvements

* **Monitoring overrides:** Open Manage overrides from a firm watch to inspect or edit model and account policies. [Override behavior](/advisor/monitoring-policies)
* **Firm page context:** Tilt Agent distinguishes Firm Setup from History and reads the effective defaults shown in Setup. [Firm Setup](/advisor/review-the-firm#setup)
* **Chat responsiveness:** Compose messages in long conversations with less typing lag and fewer layout changes around the message box.
* **Reply startup:** Tilt Agent begins preparing its first response sooner, with less waiting before the first model request.
* **Mac update notices:** Tilt for Mac 1.34.1 shows available updates in your account menu, with an avatar dot instead of an interrupting dialog.
* **Mac update installation:** Tilt for Mac 1.34.1 checks for the newest release before restarting, avoiding a restart into an already superseded update.

## Fixes

* **Constituent analysis:** Tilt Agent queries the same evaluated constituents and weights as the Tilt view, including saved selection limits.
* **Company exclusions:** The Tilt view now applies saved company exclusions when evaluating constituents, keeping excluded companies out of the result.
* **Document analysis:** Tilt Agent preserves source-authored investment views and cautions, separating reported business facts from recommendations and selection rules.
* **Optimization failures:** Failed proposals distinguish a solver failure from an infeasible portfolio, instead of treating a missing solver status as infeasibility.

**October 30, 2026**

## New

* **Account templates:** Owners and editors can define reusable settings in Firm Setup, then review selected changes before applying them to accounts. [Account templates](/advisor/account-templates/manage)
* **Templates in chat:** Ask Tilt Agent to prepare template definitions or selected account changes for review, without automatically assigning future accounts. [Template behavior](/advisor/account-templates/overview)

## Improvements

* **Firm Setup:** Find inherited defaults and account templates together, with owner-only access and approval settings in a separate section. [Firm Setup](/advisor/review-the-firm#setup)
* **Page context:** Tilt Agent now receives the general page you're viewing, including Trading's tab or Clients search, alongside the composer's page label.
* **Tilt History:** Review new ownership transfers, source attachments and removals, and catalog changes in firm-private History, without backfilling earlier activity. [History coverage](/advisor/history-coverage)
* **Stopped replies:** When you stop Tilt Agent, its reply shows a Stopped footer, including on cards, to distinguish it from completed answers.
* **Mac tab shortcuts:** Tilt for Mac 1.32.1 assigns Command-1 through Command-9 to tabs, replacing Library, Alerts, and Automations shortcuts, with Command-9 selecting the last.
* **Mac tab navigation:** In Tilt for Mac 1.32.1, switch tabs with Control-Tab or Control-Shift-Tab, or find open pages in Command-K.

## Fixes

* **Legacy sell-downs:** Prepare sell-downs even when a sleeve still targets a Legacy holding, retaining no-buy restrictions and potentially binding tax limits. [Legacy holdings](/advisor/transition-legacy-holdings)
* **Position limits:** Save fractional-percent minimum, maximum, and active-weight limits, including a 0.5% minimum, without rounding to whole percentages.
* **Construction edits:** Apply evaluates the latest completed daily publication, avoiding unsupported dates while still requiring current data and a successful evaluation.
* **Empty accounts:** Daily checks treat accounts with no positions and no positive value as having no holdings, rather than reporting a failed check.
* **Mac workspace tabs:** Tilt for Mac 1.32.1 closes other workspaces' tabs and Recently closed entries when loading a workspace, preventing cross-workspace tab resets.

**October 29, 2026**

## New

* **Account portfolios:** Combine your primary model with weighted extra sleeves in Account Setup, or ask Tilt Agent to prepare the mix. [Account portfolios](/advisor/tailor-account)
* **Sleeve defaults:** Set a reusable sleeve's direct-indexing default for new placements, while existing placements and account overrides keep their settings. [Direct-indexing defaults](/advisor/models-and-benchmarks)
* **Holding attribution:** Select a holding's Weight on an account's Holdings tab to inspect its sleeve, Tilt, or Legacy allocation. [Where holdings count](/advisor/monitoring-explained#see-where-a-holding-counts)
* **Attribution in chat:** Ask Tilt Agent which sleeves a holding counts toward, including split weights and tickers outside the model. [Holding attribution](/advisor/monitoring-explained#see-where-a-holding-counts)
* **Trading responsibility:** Owners and editors can mark linked, externally managed accounts as traded by the firm, recording a reason in Account Setup.

## Improvements

* **Account Overview:** Review performance and drift beside gains, asset-class allocation, and recent transactions, with columns that stack in narrower views. [Overview guide](/advisor/account-overview)
* **Gains:** Check unrealized gains, this year's realized gains, and remaining client budget on Overview, with budget editing and entries on Holdings. [Account gains](/advisor/account-overview)
* **Drift summary:** Overview highlights top-level sleeves and nested problems, while Optimization retains the full breakdown, dates, and limits. [Monitoring guide](/advisor/monitoring-explained)
* **Performance:** See account value and named benchmarks beside returns, and keep the previous chart visible while another period loads. [Performance guide](/advisor/account-overview)
* **International risk:** Account optimization selects Worldwide risk for international holdings or targets, including ETF constituents, while domestic portfolios retain North American risk.
* **Account exposures:** Compare sector and style exposures using the selected Axioma model, with coverage disclosures for holdings the model cannot measure.
* **History coverage:** Inspect new investment, tax, access, custody, and household decisions in expandable groups, without backfilling earlier activity. [History coverage](/advisor/history-coverage)
* **Model navigation:** Identify models in Sleeves and open their Model setup, Accounts, or Model History without losing the sleeve's own History.
* **Change impact:** Review affected accounts when changing a model's root sleeve, including customizations that will remain or stop applying.
* **Passkey help:** Follow the new guides to firm sign-in rules, member setup, and recovery, or ask Tilt Agent for help. [Firm sign-in](/advisor/require-passkey-or-two-step-sign-in)
* **Mac passkeys:** Tilt for Mac 1.30.1 opens your browser for firm passkey checks and adding passkeys, then returns you to Tilt.
* **Activity history:** Expand Tilt Agent's activity line to review its steps during a turn and after replies with multiple steps.
* **Long chats:** Tilt Agent summarizes earlier conversation sooner and shows Summarizing earlier conversation when a reply pauses for that work.
* **Automation instructions:** Put required context in saved instructions because scheduled jobs now start fresh without Main's chat history. [Automation instructions](/tilt-agent/create-automation)
* **Saved scenarios:** Reopening stored scenario results reads less data and avoids repeating completed-result verification, reducing work without changing the saved analysis.

## Fixes

* **Sleeve swaps:** Tilt Agent turns off incompatible direct indexing when proposing a replacement holding, and includes that setting change for review.
* **Blocked sleeve edits:** Before changing a shared sleeve to an incompatible holding, see which accounts or composites need direct indexing turned off.
* **Nested swaps:** Account Setup explains inherited direct-indexing conflicts before queuing an incompatible composite replacement, rather than failing when you apply it.
* **Replacement names:** Setup, drift results, and Tilt Agent identify the replacement sleeve an account holds, alongside the model sleeve it overrides.
* **Model archives:** Archiving and restoring a model sleeve keeps its model status aligned, and archived models refuse settings edits until restored.
* **Legacy assignments:** Changing risk-model identity preserves accepted legacy sell-down instructions when their holdings and replacement mix still match. [Legacy holdings](/advisor/transition-legacy-holdings)
* **Sleeve deletion:** Reassign or remove active legacy holdings before deleting a sleeve they reference, including a parent sleeve in their path.
* **Saved restrictions:** Corporate-action review recognizes existing automatic restrictions with their saved terms, avoiding duplicate confirmation when the firm already has the rule.
* **Member recovery:** Owners whose only accepted sign-in method is text messages can confirm by text code when resetting a member's methods.
* **Workspace switching:** Opening a locked firm from the workspace menu takes you through its sign-in check, then resumes the requested page.
* **Passkey sign-in:** Use the explicit Sign in with a passkey button when your browser's automatic passkey suggestion doesn't appear. [Sign-in methods](/advisor/sign-in-with-passkey-or-two-step)
* **Code lockouts:** After too many incorrect codes pause your codes for a firm, Tilt emails you about the pause and recovery options.
* **Chat history:** Shared chats and Tilt Agent's conversation reads retain replies' opening words, and card text appears once alongside the answer.
* **Scheduled briefings:** Tilt Agent uses the firm already bound to the scheduled run instead of asking you to choose it again.
* **Automation access:** Production scheduled jobs use Tilt's public app address, avoiding deployment-password errors when they read your authorized firm data.
* **Trade status:** Tilt Agent pairs partial filled quantities with recorded execution prices, and says when the custodian hasn't supplied a price.
* **ETF holdings:** Ask Tilt Agent for a fund's actual holdings, with their source and date, while keeping named-index requests distinct.
* **ETF construction:** ETF-holdings lookups avoid a query timeout while continuing to report unavailable holdings for funds without a recent eligible snapshot.
* **Scenario loading:** Portfolio scenario reads drop all reported unsupported securities together, avoiding repeated requests that remove just one holding at a time.
* **Scenario recovery:** Stored scenario reads can reconnect after a database failover, and new scenario-service processes recover from temporary startup outages.
* **Macro questions:** Ask Tilt Agent for sector-level macro analysis without a detour through the retired practice heatmap, while modeled multi-household shocks still require Pulse access.

**October 28, 2026**

## New

* **Firm sign-in rules:** Owners can require passkeys or two-step sign-in in Settings > Security, choosing allowed methods and when members confirm again.
* **Sign-in methods:** When your firm requires them, set up passkeys, an authenticator app, or text message codes for that firm in Settings.
* **Off-model holdings:** See tickers outside your model's sleeves and Tilts in Account Setup before optimizing, or ask Tilt Agent for the list. [Off-model holdings](/advisor/tailor-account#check-for-off-model-holdings)
* **Keep in Legacy:** Move an eligible off-model ticker into Legacy holdings from Account Setup, then save the change. [Legacy holdings](/advisor/transition-legacy-holdings)
* **Non-tradable holdings:** Inspect linked accounts' bonds, options, and other non-tradable positions by name and value on account, client, and household Holdings tabs.

## Improvements

* **Member recovery:** Firm owners can review and reset a member's sign-in methods for their firm without changing the member's methods elsewhere.
* **Google re-entry:** Google users can return after a firm's inactivity logout with Continue with Google, including in Tilt for Mac 1.29.1.
* **Release-rule edits:** Owners can review trade release changes in Firm Setup's shared queue, keeping unapplied edits while moving between settings groups.
* **Release-rule History:** New policy saves appear in Firm History with the person who changed them, alongside other firm settings changes.
* **History details:** Read changed models, sleeves, and investments by name, with more room for values beside long field labels.
* **History in chat:** Ask Tilt Agent about recorded changes using the same names and descriptions you see in History.
* **Inherited Tilts:** Account Setup identifies Tilts inherited from parent composites and the model Tilts that stop applying at a swapped sleeve. [Account Setup](/advisor/tailor-account)
* **Cloud chats:** Tilt for Mac 1.29.1 keeps chats running after you quit, though requests for local files still need the app open.
* **External pages:** Tilt for Mac 1.29.1 opens published Tilt and other non-app pages in your browser, keeping their headers outside app chrome.

## Fixes

* **Sleeve swaps:** Replacing a model sleeve stops its Tilts at that place, while retaining account-specific Tilts and those inherited from parent composites. [Swap behavior](/advisor/tailor-account)
* **Sleeve editors:** Open editable Definition rows by clicking their values as well as their labels, including Holds and Alternative ETFs.
* **Older History:** Scrolling through History no longer requests the same older page twice when the list's end remains visible.
* **Mac menus:** Update to Tilt for Mac 1.29.1 so menus and dialogs stay above page tabs while the page remains visible.
* **Sign-in links:** Malformed return links no longer redirect you to another website after signing in to Tilt.
* **Company limits:** Newly built score- and equal-weighted Tilts keep one listing per company, while market-cap-weighted Tilts can retain multiple listings.
* **Index selection:** Exchange-restricted indexes exclude tickers with announced moves outside allowed exchanges, while retaining moves between allowed exchanges.
* **Buyback calculations:** New strategy backtests account for compulsory buybacks below market price and skip unusable terms, without restating published index history.

**October 27, 2026**

## New

* **Mac page tabs:** In Tilt for Mac 1.25.1, open pages as tabs beside chat and switch between them without leaving the conversation.

## Improvements

* **Setup confirmations:** Review a confirmation before discarding queued changes, switching optimization modes that rewrite weight limits, or rebuilding a rule's condition.
* **Ticker lists:** Paste multiple ticker symbols into Setup searches to add them together, with feedback for unknown symbols and existing entries.
* **Setting sources:** See each field's inherited value and reset target, with Changed marks and previous values for queued edits. [Account Setup](/advisor/tailor-account)
* **Setup summaries:** See the number of queued changes beside each settings group, with clearer labels for trading costs and position weights.
* **Security shortcut:** Find your firm's inactivity timeout in Firm > Setup, with a link to owner-managed Settings > Security. [Inactivity logout](/advisor/inactivity-logout)
* **Security help:** Ask Tilt Agent to explain an inactivity sign-out or prepare a timeout change for an owner to review in Tilt.
* **Tilt placement guide:** Compare parent and leaf placement in mixed models, including effects on funds-only sleeves and account-wide trades. [Placement guide](/advisor/models-and-benchmarks)
* **Tilt book labels:** Distinguish Long-only from Long / short in the Tilt summary, with a warning that long/short books aren't investable as built.
* **Long-only construction:** Ask Tilt Agent to convert a long/short Tilt into a long-only version or copy, dropping companies with net-negative scores.

## Fixes

* **Optimization confirmation:** Confirm reruns using current saved inputs without stale-input errors, while retaining readiness checks and separate trade approval.
* **Optimization delays:** Infeasible optimizations and monitoring checks skip lengthy diagnostic re-solving by default, while retaining their feasibility checks and results.
* **Legacy tracking error:** Transition and destination estimates use historical covariance when factor coverage is missing, provided sufficient return history exists. [Calculation details](/advisor/transition-legacy-holdings)
* **Tilt charts:** Saved Tilt cards in chat read the same accessible one-year performance result as Overview, rather than a separate simulation.
* **Basket dates:** Parametric sleeve calculations use the requested trade date instead of a fixed historical cutoff, without guaranteeing saved-basket snapshot matching.
* **Setup dialogs:** Queued changes no longer cover Done, and clicking the queue keeps the dialog open while you review its changes.
* **Index construction:** When publishing an index, remove forced-in tickers before proceeding, while ordinary non-index Tilts retain their inclusion overrides.
* **Mac stability:** Tilt for Mac 1.25.1 includes steadier page tabs and wake/unlock recovery that avoids accessing windows you've closed.
* **Mac security:** Update to Tilt for Mac 1.25.1 for patched Electron dependencies and the accompanying browser-content and address-parsing security fixes.

**October 26, 2026**

## New

* **Inactivity logout:** Firm owners can enable 15-, 30-, or 60-minute timeouts in Settings > Security, with Off as the default. [Setup guide](/advisor/inactivity-logout)
* **Firm sign-in:** Inactivity logout affects only that firm, with an email code to return while other workspaces stay signed in. [What keeps running](/advisor/inactivity-logout#what-keeps-running)

## Improvements

* **Trade release rules:** Edit individual rules in dialogs, then review queued changes and explicitly Save policy before they take effect. [Release rules](/advisor/trade-release-rules)
* **Sale estimates:** Proposed share sales show saved USD estimates until fully filled, with partial fills shown separately and unpriced orders marked Priced at fill.
* **Account Overview:** Follow the new guide to account values, realized gains, remaining capital gains budget, and monitoring results. [Overview guide](/advisor/account-overview)
* **Wash-sale settings:** The updated guide explains ticker-level and account-wide overrides, including how to restore wash-sale prevention. [Tax-aware management](/advisor/tax-aware-management)
* **Legacy holdings:** The expanded guide distinguishes transition and destination tracking error, with worked sale-threshold and gains-budget examples. [Legacy calculations](/advisor/transition-legacy-holdings)
* **Advisor guides:** Find documentation grouped by task, from firm setup and model building through account management, monitoring, and trading. [Advisor documentation](/advisor/overview)
* **Background work:** Running jobs stay in the chat header, while replies cite the job instead of repeating separate completion badges and notes.
* **Running jobs:** Read job names, elapsed times, and current activity in steady two-line rows, including in the phone's job list.
* **Phone navigation:** Tilt opens on Library, with chat available as an overlay rather than a separate full-screen page.
* **Card links:** Open objects linked from chat cards in new browser tabs with Command-click or middle-click, while ordinary clicks keep their existing behavior.

## Fixes

* **Factor analysis:** Account comparisons use the saved reporting benchmark, or SPY when none is configured, and label the benchmark in results.
* **Custodian access:** Owners acknowledge the disclosure before connecting or replacing keys, while reads, sync, and disconnection remain available. [Connection guide](/advisor/connect-custodian)
* **Idle tabs:** Returning to an outdated web tab reloads it safely, or offers Reload when unsaved work needs protection.
* **Interrupted replies:** Chat marks text interrupted before Tilt Agent restarts a step, instead of leaving repeated passages without explanation.
* **Phone chat links:** Tapping a link to the page beneath the chat now closes the overlay so you can see that page.
* **Phone headers:** Library, Alerts, and advisor collections show one page heading instead of a duplicate title bar above it.
* **Error recovery:** Try again and other recovery buttons remain readable in light theme instead of appearing disabled.

**October 23, 2026**

## New

* **Firm:** Review your book's total value, account counts, and searchable security holdings from the new sidebar page. [Review the firm](/advisor/review-the-firm)
* **Firm History:** Review recorded changes across the firm and filter by object kind, person, or date range. [History guide](/advisor/review-the-firm#history)
* **Custodian management:** Firm owners can connect Alpaca Broker API, replace keys, and disconnect through the custodian card in their own Tilt sign-in. [Guide](/advisor/connect-custodian)
* **Custodian accounts:** Review linked client accounts and custodian restrictions, with Sync now available to firm owners in Tilt. [Sync details](/advisor/connect-custodian#4-sync-and-review-client-accounts)
* **Custodian audit:** Review records of connections, key replacements, and disconnections without exposing the keys. [History coverage](/advisor/history-coverage)
* **Sleeve nesting:** Build models up to ten levels deep, subject to a 500-place limit per sleeve tree. [Model guide](/advisor/build-model-portfolio)

## Improvements

* **Firm Setup:** Edit firm defaults on Firm > Setup and apply grouped changes together, with trade release rules saved separately by owners. [Setup guide](/advisor/review-the-firm#setup)
* **Sleeve monitoring:** See each Tilt's own row and nested sleeves' current and target weights in Overview after a fresh drift check. [Measurement details](/advisor/monitoring-explained)
* **Legacy setup:** Continue from an applied sleeve swap or direct-indexing change into Legacy holdings, with an explicit sale threshold and confirmation. [Legacy holdings](/advisor/transition-legacy-holdings)
* **Legacy setup in chat:** Ask Tilt Agent to prepare an eligible legacy-holding assignment for review after enabling direct indexing. [Assignment guide](/advisor/transition-legacy-holdings)
* **Page navigation:** Open client, household, and model views at their own addresses, including individual accounts, with browser Back support.
* **Account switching:** Choose another account from the menu beside the account title instead of the separate band above it.
* **Model settings:** Find a model's measurement benchmark and other settings under Setup, with line tabs for switching views. [Benchmark guide](/advisor/models-and-benchmarks)
* **Tilt construction:** Ask Tilt Agent for per-group rankings, such as sector-neutral momentum, using the construction language's supported methods and recipes.
* **Change reviews:** Follow the new guide to ask Tilt Agent for batched summaries of recorded model and sleeve changes. [Create a change review](/tilt-agent/review-changes-automation)

## Fixes

* **Direct indexing:** Reset a customized sleeve inside a composite to the model's setting, with warnings when other places share the account override. [Tailoring guide](/advisor/tailor-account)
* **Models:** Saved models no longer show a Draft badge in the table, while archived models keep their Archived label.
* **Account cards:** Read account names, values, and details without overlapping text on narrow screens, and start optimization from the account's Optimization view.
* **Main chat:** Opening an empty Main chat now clears Loading chat so you can send the first message.
* **Rebalance reviews:** Read valuation failures as missing required valuation data, rather than assuming the cause is missing holding prices.
* **Watches:** New watches use the active firm by default, while personal watches require an explicit personal choice.
* **VIX watches:** Tilt Agent distinguishes a one-day move from a move over a longer window when preparing a watch.
* **Sign-in:** Loading screens keep the heading and Tilt wordmark aligned instead of jumping as you move between sign-in and workspace loading.
* **Web security:** Updated the web framework to address cache, image-processing, and Server Action security vulnerabilities.

**October 22, 2026**

## New

* **Account performance:** Compare after-fee account returns with before-fee models and benchmarks in Overview or Tilt Agent. [Calculation details](/advisor/account-performance)
* **Household performance:** Compare after-fee household returns with before-fee model and benchmark blends, weighted by daily value. [Household calculations](/advisor/account-performance#read-a-households-performance)
* **Proposals:** Inspect Trade attribution, its tilts, and Constraint attribution reports for the optimizer's result before cash adjustments, rather than final orders. [Report details](/advisor/reports-and-backtests)
* **Connections:** Ask Tilt Agent about connected apps, tool permissions, and repeated approvals, or have it prepare a permission change for your review. [Manage permissions](/tilt-agent/connect-mcp-server#choose-what-tilt-agent-may-do-with-each-tool)
* **Custodians:** Ask Tilt Agent for connection status, environment, key expiry, sync time, and client-account counts within your brokerage-account viewing permissions.
* **Tilt construction:** Favor existing constituents near a maximum-count cutoff with Constituent buffer, including in fresh backtests.
* **Construction defaults:** New rulebooks start with a 0% Constituent buffer, while existing rulebooks retain 10%.

## Improvements

* **Clients:** Switch between client and household views, expand accounts, and find items needing attention with account cards and sleeve filters.
* **Households:** Rename a household on its page and review the change in History, without renaming clients outside a household. [Review History](/advisor/see-who-changed-an-account)
* **History:** Read sleeve changes by name and before-and-after settings, with descriptive labels for removed sleeves and deleted account-only edits. [History coverage](/advisor/see-who-changed-an-account)
* **Firm restrictions:** Ask Tilt Agent to edit corporate-action defaults or remove automatic restrictions within your permissions. [Existing restrictions survive cleared defaults](/advisor/corporate-action-restrictions).
* **Models:** Read the updated guide's explanation of existing composite tilt calculations for nested sleeves and whole-model allocations. [Allocation guide](/advisor/models-and-benchmarks)
* **Settings:** Search for connected apps and tool permissions, and see app logos from the first visit to connection settings.
* **Connected apps:** Open tool permissions from chat calls and see supported views below approved calls. [Call details and approvals](/tilt-agent/connect-mcp-server#approve-or-deny-a-call-in-the-chat)
* **Connected apps:** Keep chatting during approved calls or Stop the waiting reply without undoing work the app has done.
* **Feedback:** Attach or paste PNG or JPEG screenshots, review them before sending, and share them through private storage with employee-only links.

## Fixes

* **Model performance:** Keep historical comparisons when constituents listed after the requested start, subject to available prices. [Dates and dividend treatment](/advisor/account-performance#how-each-line-is-measured)
* **Sleeve measurements:** Measure supported sleeves despite off-model holdings after a fresh evaluation, without changing coverage requirements. [Measurement limits](/advisor/monitoring-explained)
* **Proposal explanations:** Tilt Agent checks restriction sources without treating them as proof of a trade's cause, and reports missing evidence. [Report details](/advisor/reports-and-backtests)
* **Client creation:** Slow price or risk reads after creating one client no longer hold up another client-creation request for the firm.
* **Firm access:** Removing a member revokes their outside-app grants for that firm without restoring them on rejoining or affecting other firms.
* **Connections:** Keep connections and tool permissions separate across firms by connecting each app in each firm where you need it. [Connection guide](/tilt-agent/connect-mcp-server)
* **Tool approvals:** Tilt asks again when an Always allow tool definition changes or an older saved choice lacks a version.
* **Connection audit logs:** Tilt Agent can read queued firm audit entries for permission changes, approval answers, and qualifying calls that can change app data.
* **Audit visibility:** Connected-app audit entries are available to Tilt Agent but do not appear in the app's History sections.
* **Connection setup:** Recover confirmation cards and sign-in results when returning to chat without repeating the connection proposal.
* **Backtests:** Non-IOSCO backtests tolerate missing corporate-action currency or FX data with approximate results, while IOSCO calculations still require valid conversions.
* **Index performance:** Fixed benchmark lookup failures when several ticker records use the SPY symbol.
* **Tilt construction:** Retired consensus sketches and the frozen-holdings function, which now errors in saved expressions, while keeping methodology research available.

**October 21, 2026**

## New

* Account setup: Hold something other than the model's choice in any sleeve of an account's model, at any level. Pick another of your firm's sleeves, or set an ETF, index, Tilt, security, or basket for that account only. The model's weights still apply. [Guide](/advisor/tailor-account#change-what-a-sleeve-holds)
* Configurations: When several accounts hold the same account-only edit in a sleeve, save it as one sleeve with Save as sleeve, so a later change happens once for all of them. [Guide](/advisor/compare-account-configurations#4-save-a-shared-edit-as-a-sleeve)
* History: Review recorded changes on account, client, household, and model pages, including who acted, when, and before-and-after settings. Open the source conversation when you have access. History has coverage limits; a missing entry does not establish that no action occurred. [Guide](/advisor/see-who-changed-an-account)
* Trading: Owners can configure trade release rules that flag proposals and restrict eligible senders. Review flags and their evidence in Trading > To review. Tilt rechecks authority and the whole account proposal before accepting a send; flags remain visible to eligible senders. [Guide](/advisor/trade-release-rules)
* Models: Set a measurement benchmark in Settings or ask Tilt Agent to set it. Compare historical performance and estimated annualized risk against that benchmark without changing construction or trading targets. Risk estimates depend on available coverage and do not predict returns.

## Improvements

* Models: Before you apply a model or shared-sleeve change, the queue says which account customizations move with it or stop applying. [Guide](/advisor/build-model-portfolio#change-what-a-composite-holds)
* Account setup: When the model drops a sleeve where an account changed the holding, or a customized sleeve inside a composite, the customization stays saved, shows as Not in the model, and applies again if the sleeve returns. [Guide](/advisor/tailor-account#when-the-model-drops-a-customized-sleeve)
* Legacy holdings: Setup warns when a sleeve you're changing has a legacy position selling down into it, and flags the sell-down plan for review.
* Models: View historical growth, annualized return, volatility, and maximum drawdown even without a measurement benchmark. With a benchmark, the chart adds its comparison. The displayed dates follow loaded price history, so a midnight rollover need not hide the chart while overnight prices arrive.
* Backtests: See Average annual turnover in a Tilt's backtest metrics after a fresh run. This divides simulated rebalance turnover by the observed years, excludes initial formation, and shows Unavailable when the estimate or duration is missing.
* Firm restrictions: Choose when a corporate-action restriction starts and let it end at midnight UTC on the event's effective date. New defaults use event-date expiry. Existing trading-pause defaults also move to event-date expiry while retaining their lead times; existing restrictions keep their saved terms. [Guide](/advisor/corporate-action-restrictions)
* Restrictions: Keep active rules visible while expired and scheduled restrictions sit under Outside active dates. Open Condition not met for rules whose conditions are false. These sections preserve the saved rules and let you edit them.

## Fixes

* Account measurements: Corrected ownership of held ETF wrappers, configured alternatives, and former benchmark constituents across sleeve drift and tracking-error measurements. Proposals and monitoring share dated eligibility and the factor-first estimation policy; incomplete coverage can use supported historical returns. Fresh evaluations are required, and missing or stale data remains unmeasured. [Guide](/advisor/monitoring-explained)
* Proposals: Retain custom-benchmark tracking-error estimates after order rounding and filtering. These describe the optimizer's solution, not a new risk calculation at the executable order weights; older saved proposals remain unchanged.
* Trade reports: Restored constraint attribution for continuous allocation after asset selection and identified embedded-gain purchase restrictions in new reports. Tilt Agent distinguishes a restriction's origin from evidence that it caused a trade. Historical reports remain unchanged; a no-buy restriction does not prohibit selling. [Guide](/advisor/reports-and-backtests)
* Account backtests: Preserve the requested tax-awareness comparison instead of replacing it with today's remaining annual gains capacity. Explicit historical tax budgets and gains targets still apply.
* Account setup: Fixed ticker selections disappearing during a pointer click when adding restrictions. Composite sleeve editors also keep sleeve names visible beside their target percentages.
* Tilt construction: Preserve newly distributed holdings and their booked shares when another corporate action occurs before the new holding has a price. Missing prices remain unavailable; this does not repair historical index records.
* Tilt construction: Keep valid market-cap data for size classification and total-cap rankings when free-float data is missing. Float-dependent screening reports the missing data rather than treating it as zero.
* Tilt construction: Fixed whole-number grouped counts failing during construction.

**October 20, 2026**

## New

* Models: Assign a model to several accounts from its Accounts view with Add accounts. Review a warning before replacing an account's own sleeves or customizations. Tilt saves each account separately and identifies any it could not update. [Guide](/advisor/build-model-portfolio#5-assign-the-model-to-accounts)
* Shared sleeves: Create a composite, add or remove its sleeves, change their shares, and set their tilts or direct indexing. Review the queued change before applying it across the models that hold the composite. The review identifies accounts that keep their own settings and customizations that stop applying when a sleeve is removed. [Guide](/advisor/build-model-portfolio)
* Firm restrictions: Configure automatic corporate-action rules in Settings > Restrictions. Tilt applies the firm's saved rules to relevant events and notifies advisors when restrictions activate or end, according to their notification preferences. Changing a default affects new restrictions; existing restrictions keep their saved terms. These rules do not submit trades.
* Connections: Approve a connected-app tool call in a Tilt chat after reviewing the app, tool, and values to be sent. Allow once sends that call; Deny sends nothing. Always allow is offered when you have no saved choice for the tool. Automations and chats in other apps still cannot request this approval. [Guide](/tilt-agent/connect-mcp-server#choose-what-tilt-agent-may-do-with-each-tool)

## Improvements

* Connected apps: Expand a supported view to full screen using its own Edit or expand control. Close returns it to its chat card without reloading the view. [Guide](/tilt-agent/connected-app-views#when-a-view-fills-the-screen)
* Connected apps: Use a view without a separate Use this view step. Tools shared with Tilt Agent follow your saved tool permissions; calls that need approval show a Run a tool dialog. Tools offered only to the view run when the view asks, unless a permission you saved earlier requires approval or blocks them. [Guide](/tilt-agent/connected-app-views#when-a-view-runs-a-tool)
* Tax reports: For new taxable optimization runs, inspect the selected lots behind proposed sales, including quantities, proceeds, disposed cost basis, and estimated gains or losses. Read pooled loss recognition in the reconciliation; those lots have no per-lot recognized amount. Historical reports remain unchanged, and the figures are proposal estimates, not executed-trade records. [Guide](/advisor/reports-and-backtests)
* Tilt construction: Build company-selected baskets that include multiple share classes without a duplicate-listing error. Tilt sizes each company once and splits that weight across its selected listings.

## Fixes

* Account setup: See archived sleeves that your model still holds, including their sub-sleeves, and save account customizations without losing those allocations. [Guide](/advisor/models-and-benchmarks#archived-sleeves-stay-in-the-models-that-hold-them)
* Change reviews: Fixed direct-indexing previews for sleeves that also appear inside composites. The review now shows the nested places an account-wide edit affects. A saved sleeve customization no longer appears to have failed if its chat card could not be stored.
* Models: Keep the Models list and a model's Allocation, Settings, and Accounts views available when its Configurations summary fails to load.
* Firm restrictions: Fixed corporate-action controls changing position while the restriction settings load.
* Corporate-action proposals: Corrected saved weights and concentration checks for standalone proposals involving splits, reverse splits, bonus issues, or stock dividends. Tilt values the adjusted share counts at prices in the same share units.
* Tilt construction: Preserve the minimum-trading-history exemption for held spin-off securities during scheduled and news rebalances. Other eligibility and ranking rules still apply; this change does not extend to backtests.

**October 19, 2026**

## New

* Models: See a model's sleeves and sub-sleeves in an allocation tree, with each sleeve's share of its parent and of the whole model. [Guide](/advisor/build-model-portfolio)
* Account setup: Apply account-specific tilts or direct indexing to sub-sleeves inside a composite.
* Models: See accounts grouped by their sleeve configurations, including tilts, direct indexing, and holding substitutions. Open a group to find its accounts and their Setup pages. [Guide](/advisor/compare-account-configurations)
* Connected apps: View an app's own interactive charts and controls inside the Tilt chat. YCharts support is available through your connection. [Guide](/tilt-agent/connected-app-views)
* Connections: Choose Always allow, Needs approval, or Blocked for each connected app's tools in Settings > Connections > Tool permissions. For now, Needs approval stops the call and Tilt Agent explains what it intended to do; it does not open an approval dialog. [Guide](/tilt-agent/connect-mcp-server#choose-what-tilt-agent-may-do-with-each-tool)
* Connections: Connect public MCP servers that need no sign-in, such as Excalidraw, from Settings > Connections.
* Checks: Set VIX watches for level crossings, rapid percentage changes, sustained stress, normalization, or unusual readings against the past year's history. Continuous-signal checks support percentage-change windows and consecutive-observation conditions.

## Improvements

* Models: Compare models in a table with allocation bars, sleeve and account counts, configurations, and assets under management with the valuation date.
* Shared sleeves: See which models and accounts a shared composite change affects before applying it.
* Chat: Use separate controls to return to Main, open Chats, and identify the current conversation. On mobile, chat opens over the page while preserving your drafts, reading position, and ongoing work. [Guide](/tilt-agent/advisor-chats)
* Chat: Keep the current page visible in Looking at while you chat, so you can check the context Tilt Agent receives. [Guide](/tilt-agent/ask-about-page)
* Portfolio: Open a Tilt's Portfolio tab with fewer waits. The holdings table loads before optional theme-history charts.
* Scenario analysis: Reduced failures when several analyses run at once and improved recovery from dropped connections.
* Scenario analysis: Improved treatment of company and industry events that previously returned no meaningful effects.
* Tilt construction: New systematic baskets start with quarterly rebalancing and reconstitution. You can choose another schedule or disable it; existing baskets keep their settings.
* Tilt construction: Annual liquidity screening accounts for a newly listed company's shorter trading history.

## Fixes

* YCharts: Fixed charts failing to appear in browser tabs opened before chart support launched.
* Connected apps: Fixed chart copying in Chrome and Edge and in Tilt for macOS 1.19.1 when the app declares clipboard support.
* YCharts: Save a chart from its Save button after confirming the download link in Tilt.
* Connected apps: Download files an app provides, such as chart images, CSV tables, or reports, after reviewing Tilt's download confirmation.
* Scenario analysis: Fixed affected ticker lookups that rejected names such as ACN, KD, MSI, and SAIC as ambiguous. A results request now returns the supported securities and identifies any it could not resolve.
* Scenario analysis: Clarified when Ripples ran without moving another economic factor, replacing the misleading zero-effects message.
* Scenario analysis: Label the response window in trading days so the modeled repricing period is clear.
* Account comparisons: Fixed failures displaying what-if comparison cards and preserved the order of the targets you requested.
* Change reviews: Fixed approval handling so Tilt Agent cannot apply its own change proposals or approve its own trades.
* Proposals: Keep the optimizer's risk estimates visible after order rounding or filtering, rather than dropping them from the saved proposal. These estimates describe the optimizer's solution, not a fresh risk calculation at the final order weights.
* Scenario analysis: Corrected direction handling for currency shocks such as a falling pound.


# Compare a model's account configurations
Source: https://docs.tilt.now/advisor/compare-account-configurations

See how a model's accounts customize its sleeves, and save an edit several accounts share as a sleeve.

A model's accounts can customize its sleeves with their own holdings, tilts, or direct indexing. Use configurations to see those differences from the model, without opening each account. A configuration is a group of accounts that customize the model's sleeves in exactly the same way. Most screenshots show the **Global 80/20** model in the made-up Northwind Family Office practice; the holding examples show **Balanced Growth** in the made-up Cedar Ridge Wealth practice.

[Models and benchmarks](/advisor/models-and-benchmarks#configurations-group-accounts-that-match) explains which differences count.

## 1. Find models with customized accounts

Open **Models** in the sidebar. The **Configurations** column summarizes each model:

| Value | Meaning |
| - | - |
| **As modeled** | Every account follows the model's sleeves. |
| **1 configuration** | Every account makes the same customization. |
| **5 configurations** | The accounts form five groups, which can include **As modeled**. |
| **—** | No account uses the model. |

![Models table with a Configurations column. Global 80/20 shows 5 configurations; ETF Starter, Global 60/40, Growth Core, and Income & Real Assets show As modeled.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-models-index.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=5adb92e47c8dfb1ebabb1be194587969)

Global 80/20's 9 accounts form 5 configurations. The other models' accounts all follow their models.

Select a configuration count to open the model at its **Configurations** section.

## 2. Read the groups

**Configurations** sits below the Allocation tree. **As modeled** comes first. The other groups follow, the largest number of accounts first, then the largest value. Each group lists the sleeves it changes and what its accounts set there, with its account count, its value, and a bar for its share of the model's value.

![Configurations section listing As modeled with 3 accounts, US Large Growth DI on with 2 accounts opened to Chen Household IRA and Lindqvist Joint, Developed ex-US Low Carbon +5% with 2 accounts, and a group with Quality Leaders +10% and DI on for US Large Growth plus Low Carbon +5% on US Large Value.](https://mintcdn.com/tilt/F6YFsZbsydHw-1LM/images/advisor/northwind-configurations.jpg?fit=max\&auto=format\&n=F6YFsZbsydHw-1LM\&q=85\&s=340f34a9398431588df51591fb869746)

Four of Global 80/20's five configurations, with the US Large Growth direct indexing group open to its two accounts.

Each line names a sleeve and the change:

| Line | Meaning |
| - | - |
| US Large Growth (IUSG) · DI on | The accounts direct index this sleeve. |
| Developed ex-US (EFA) · Low Carbon +5% | The accounts apply the Low Carbon tilt to this sleeve at +5%. |
| US Mid Cap → US Mid Cap Core | The accounts hold your US Mid Cap Core sleeve in place of US Mid Cap. |
| US Small Cap → IJR | The accounts each hold IJR in place of US Small Cap, as their own edit. |

![Configurations section with a group US Small Cap → IJR, 2 accounts, opened to jordan-patel-taxable and morgan-reyes-taxable, with a Save as sleeve link and the text 2 accounts share this edit. Saved as a sleeve, a later change happens once. A second group reads US Mid Cap → US Mid Cap Core, 1 account.](https://mintcdn.com/tilt/F6YFsZbsydHw-1LM/images/advisor/cedar-configurations-shared-edit.jpg?fit=max\&auto=format\&n=F6YFsZbsydHw-1LM\&q=85\&s=4448372680aea93f3956561cacbff939)

Balanced Growth in the made-up Cedar Ridge Wealth practice. Two accounts hold IJR in place of US Small Cap.

Hover over a sleeve name to see its full place in the model, such as **US Equity › US Large Cap › US Large Growth (IUSG)**. Select a group to list its accounts, then select an account to open its **Setup**.

## 3. Check one sleeve

The Allocation tree adds a **Customized in** column when any account differs from the model. A sleeve's count opens a list of the accounts that customize it, each with its change, under the model's own setting. A composite shows how many accounts change something inside it, such as **4 accounts inside**.

![Customized in list for US Large Growth (IUSG) with Model: No tilts, Direct indexing off. Chen Household IRA, Lindqvist Joint, and Okafor Education Trust show DI on; Okafor Family Trust shows Quality Leaders +10% and DI on.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-customized-in.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=e3082c6c01498bcd88b2ca5ddcf63c28)

Four accounts customize US Large Growth. The model sets no tilts and leaves direct indexing off.

## 4. Save a shared edit as a sleeve

When two or more accounts use **Edit for this account…** to hold the same thing in the same sleeve, their group shows **Save as sleeve**. Name the sleeve and save it. Those accounts then hold the new sleeve, so a later change happens once for all of them, and other models can use it too.

## 5. Ask Tilt Agent

Tilt Agent reads the same groups. Ask, for example, **"How many distinct setups do the Global 80/20 accounts have, and which accounts direct index US Large Growth?"** It reports the configurations and names the accounts in a group.

Apart from **Save as sleeve**, configurations are read-only. To change an account's customization, open its **Setup** and follow [Tailor a client account](/advisor/tailor-account). To change what every account on the model holds, change the model: [Build a model portfolio](/advisor/build-model-portfolio).


# Set conditional rules and preview their effect
Source: https://docs.tilt.now/advisor/configuration-and-rules

Add rules to an account, model, or organization, then preview account changes before saving.

Use Dynamic Rules to change an optimization setting while a condition holds or during a date window. For example, you can set a 3% USD cash buffer when an account's value falls below \$250,000. You can also add conditions to ticker restrictions and asset bounds.

| To change | Account or model | Firm Setup |
| - | - | - |
| Conditional settings, such as cash buffer or turnover limit | **Rules** | **Rules** |
| Conditional no-hold, no-trade, or ticker asset bounds, including conditions on numeric ticker fundamentals | **Constraints** | **Constraints** |

Choose the account, model, or organization that should own the change. Model and organization changes affect more than one account, so check their scope before applying them.

![Organization defaults feed a model portfolio and client account; account settings take precedence for scalar values; matching Dynamic Rules resolve settings for a selected date.](https://mintcdn.com/tilt/5JZccZsU2ZaE43PT/images/advisor/settings.svg?fit=max\&auto=format\&n=5JZccZsU2ZaE43PT\&q=85\&s=7988fcddc0699c7d437990c7cfd8a33d)

An account combines saved settings with any matching Dynamic Rules.

## 1. Open the rule editor

### For one account

1. Click **Clients** in the left navigation. Check **More** if it is hidden.
2. Click the client's name in the list.
3. Select a named account near the top of the client page. Use the **more** menu if the account is hidden. A client with one account opens that account automatically.
4. Click **Setup**, beside **Optimization** and **Holdings**. These tabs appear when you select an individual account rather than **All accounts**.
5. Scroll past **Model** and **Sleeves** to **Settings**.
6. Click the **Rules** row below **Constraints**. The **Rules** dialog opens.

Check the account name above the tabs. Edits here apply to that account only.

![The account Settings list includes Tax, Transactions, Optimization, Constraints, and Rules; Rules is the last row.](https://mintcdn.com/tilt/CgV6P4zm-c-xhzLn/images/advisor/account-settings.jpg?fit=max\&auto=format\&n=CgV6P4zm-c-xhzLn\&q=85\&s=099726ea449ec2aa68695e8ac03d60ff)

Open Rules from the Settings list in the account's Setup tab.

### For a model

1. Click **Models** in the left navigation, or under **More**.
2. Click the model's name.
3. Click **Setup** on the model page.
4. Click the **Rules** row.

Model rules apply to accounts following that model, subject to each account's own settings and rules.

### For the organization

1. Click **Firm** in the left sidebar.
2. Click **Setup**, then **Rules**.

Organization rules provide defaults for models and accounts, subject to their more specific settings and rules.

## 2. Add a conditional setting

In the rule editor:

1. Click **Add a rule for…** and choose **USD cash buffer**.
2. Enter **3** in the value field. The field shows **%**, so this means 3%.
3. Click **Add a condition**.
4. Choose **account value**, **is below**, and enter **250k**. Money fields accept values such as `$250,000`, `250k`, and `1M`.
5. Review the sentence: set the USD cash buffer to 3% when account value is below \$250,000.
6. To limit the rule to a date window, click **Add dates** on the card and enter the dates. If you supply both a condition and dates, both must hold.
7. For an account or model, click **Queue changes**. Organization edits queue as you make valid changes.

![Rules dialog showing USD cash buffer set to 3%, account value is below 250k, Not active now, and Queue changes.](https://mintcdn.com/tilt/8uWMvqqh34PlxwLi/images/advisor/conditional-cash-buffer.jpg?fit=max\&auto=format\&n=8uWMvqqh34PlxwLi\&q=85\&s=bed16413c6da5acf8ca354a13970723e)

This draft sets a 3% USD cash buffer when account value is below \$250,000. It is not active for the example account's current value.

You can also choose **USD cash amount**, **Turnover limit**, **Active risk limit**, **Tax-loss harvest threshold**, or **Gains target**. Use at least a condition or dates for a rule. For an unconditional value, edit the setting in its usual settings group.

Click **Add another condition** to choose **all** or **any** of the comparisons. **All** requires each comparison to hold; **any** requires at least one. The editor supports one group of comparisons per rule.

On an account, check the card's **Active now** or **Not active now** status. It describes whether the rule matches the current account context and dates. It does not mean you have saved the draft or placed trades.

Use the up and down controls to order rules for the same setting. Tilt uses the first matching rule, reading top to bottom. If none matches, Tilt uses the setting's saved value.

### Check inherited settings and rules

For settings such as cash buffer or turnover limit, an account value takes precedence over the model's value, which takes precedence over the organization's value. A missing value inherits; an explicit zero is a value. The assigned model supplies allocation membership and weights when it defines them. Check both the saved value and the effective value when a setting appears not to take effect.

Account rules run before model rules, which run before organization rules. An explicit account value for a setting prevents inherited rules for that setting from taking effect. An explicit model value prevents organization rules for that setting from taking effect. Rules at the level that sets the value still apply.

The editor shows inherited rules as read-only cards with source badges linking to where you can edit them. **Not used** identifies an inherited rule blocked by a more specific saved value. A rule outside the sentence editor's supported shape appears as read-only text; remove it and add a new card to change it in the interface.

## 3. Add conditional restrictions or bounds

Open **Constraints** for an account, a model, or the firm's **Setup**:

| Scope | Location |
| - | - |
| Account | **Clients → client → named account → Setup → Settings → Constraints** |
| Model | **Models → model → Setup → Constraints** |
| Organization | **Firm → Setup → Constraints** |

Search for a ticker under **No-hold tickers** or **No-trade tickers**, then use **Add a condition** on its row. You can also set its **From** and **Until** dates. On an asset-bound row, enter its limits and add a condition; asset bounds have no date window. Queue account or model changes with **Queue changes**.

A restriction stops applying at its **Until** date. Tilt keeps the saved row but moves it out of the main list into a collapsed **Outside active dates** section, alongside rows whose **From** date hasn't arrived. Rows whose condition doesn't hold today collapse into **Condition not met**. Expand either section to review or edit those rows. To see who added or changed a restriction and when, open [History](/advisor/see-who-changed-an-account) for the account, model, or firm.

Conditions on these rows can compare account values or numeric fundamentals of the row's ticker, such as **market cap**, **P/E ratio**, and **dividend yield**. The condition picker shows the variables available for that restriction or bound.

For example, to exclude NVDA above a market-cap threshold:

1. Search for **NVDA** under **No-hold tickers** and select it.
2. Click **Add a condition** on the NVDA row.
3. Choose **market cap**, **is above**, and enter the threshold, such as **500M** for \$500 million.
4. Review the sentence and click **Queue changes** before previewing or applying the account draft.

![NVDA no-hold row showing market cap is above 500M, Applies when market cap is above \$500,000,000, and Checked ticker by ticker.](https://mintcdn.com/tilt/8uWMvqqh34PlxwLi/images/advisor/conditional-ticker-fundamental.jpg?fit=max\&auto=format\&n=8uWMvqqh34PlxwLi\&q=85\&s=619382a698b48eead1ba93f78309626f)

A ticker-specific no-hold condition compares NVDA's market cap with \$500 million. Tilt checks the condition ticker by ticker.

Use the same condition editor on a **No-trade tickers** row or an **Asset bounds** row to make that restriction or weight limit depend on the ticker's numeric fundamentals. Edit these conditions alongside the ticker they affect.

![Constraints editor showing TSLA with unrealized gain is above 50k, empty From and Until dates, and Active now.](https://mintcdn.com/tilt/8uWMvqqh34PlxwLi/images/advisor/conditional-no-hold.jpg?fit=max\&auto=format\&n=8uWMvqqh34PlxwLi\&q=85\&s=978525d23feae63874bc6327e72280bf)

The TSLA no-hold draft applies while unrealized gain is above \$50,000. Its date fields are empty, so only the condition limits when it applies.

| Constraint | Effect when active |
| - | - |
| No-hold | Excludes the ticker from the optimized holdings, unless a no-trade restriction also applies. |
| No-trade | Prevents trading the ticker, including selling an existing position. It takes precedence when no-hold also applies. |
| Asset bound | Limits the ticker's weight according to the bound. |

No-hold and no-trade restrictions combine across organization, model, and account. Adding an account restriction preserves the restrictions it inherits.

To have Tilt add firm restrictions around corporate actions, [configure automatic corporate-action restrictions](/advisor/corporate-action-restrictions).

For portfolio-wide allocation or custom factor limits, [set factor exposure bounds](/advisor/set-factor-exposure-bounds) in the same **Constraints** editor. That guide covers the exact factor names, numeric units, and full-list inheritance behavior.

To allow an inherited restriction, find the ticker's inherited row and click **Allow for this account** or **Allow for this model**. Enter a reason and click **Allow**. The allowance lifts broader-level restrictions for that ticker and restriction kind. The row shows the reason; **Undo** removes the allowance. Apply the queued change to save it.

For asset bounds, the account's bound for a ticker takes precedence over the model's, and the model's takes precedence over the organization's.

## 4. Preview an account draft

Before applying account rules, restrictions, bounds, or allowances:

1. Close the editor with **Queue changes**.
2. Click the **changes queued** pill at the bottom of the account page.
3. Review the old and new values in **Queued changes**.
4. Click **Preview the effect** and wait for the optimization results.

![Queued changes panel showing the proposed conditional 3% cash buffer, Preview the effect, Discard all, and Apply 1 change.](https://mintcdn.com/tilt/8uWMvqqh34PlxwLi/images/advisor/rules-preview-entry.jpg?fit=max\&auto=format\&n=8uWMvqqh34PlxwLi\&q=85\&s=330ee09904dbf00109f07a38a69b4ac5)

The queued rule is still unsaved. Preview the effect runs the comparison; Apply saves the draft and Discard all removes it.

| Preview column | What Tilt optimizes |
| - | - |
| **Saved** | The account's saved configuration. |
| **Today** | The account with the queued rules and constraints, using today's context and dates. |
| **When it applies** | A scenario with adjusted account-level condition values to show the conditional effect, when available. |

Compare tracking error, turnover, holdings count, estimated tax, and ticker-weight changes. The optimizer may leave some metrics unreported, which the table shows as **—**.

Read any warning about rules the scenario leaves out. The **When it applies** run keeps today's date and ticker-specific values; it may not reach a future date window, a ticker-specific condition, conflicting conditions, or a later rule blocked by the first match. This scenario is a what-if optimization, rather than a forecast or historical replay.

> [!NOTE]
>
> The account preview includes queued rules, no-hold and no-trade restrictions, asset bounds, and inherited-restriction allowances. Other queued Setup changes wait for **Apply** and do not enter this preview. Model and organization editors do not provide this account-specific draft preview.

Preview saves nothing. If you edit the draft, run the preview again before relying on its results.

## 5. Apply or discard, then verify

In **Queued changes**, select **Discard all** to abandon the draft, or **Apply** to save it. Reopen the same settings page or editor and refresh the page to check that the saved cards, values, and allowance reasons match your intent.

Apply or discard account changes before starting an optimization from the **Optimization** tab. Saving rules changes optimization inputs; it does not place trades. [Review a rebalance](/advisor/review-rebalance) covers the later trading workflow.

## Use Tilt Agent

Open **Chat** in the left navigation and name the client, account, and proposed change. For example:

> For Maya Patel's Revocable Trust, set the USD cash buffer to 3% when account value is below \$250k. Show the proposed rule and preview its effect. Keep the other rules and wait for my confirmation before saving.

For a restriction:

> For Maya Patel's Revocable Trust, don't hold TSLA while the account's total unrealized gain is above \$50k. Show what you'll save, keep inherited restrictions, and wait for my confirmation.

Review the target account, condition, dates, value, and retained rules before confirming. After the save, ask Tilt Agent to read back the saved configuration and open the account's Setup through its result link to check the card. You can also ask for a dated simulation without saving a change.

For alerts about drift, cash bands, and exposure, [manage monitoring policies](/advisor/monitoring-policies). For API rule formats, schema, validation, and simulation endpoints, see the [Dynamic Rules API guide](/dynamic-rules/guide).


# Connect and manage your firm's Alpaca custodian
Source: https://docs.tilt.now/advisor/connect-custodian

Connect your firm's Alpaca Broker API keys to Tilt, then replace the keys, sync client accounts, or disconnect from the custodian card.

Your firm connects its Alpaca Broker API keys to its Tilt organization. One connection covers every client account the firm holds under its Alpaca correspondent code. Tilt reads those accounts through it and sends approved trades through it.

## Who can do what

| Action | Who can do it |
| - | - |
| See the connection's status and its client accounts | Firm owners, editors, and viewers |
| Connect, connect another, replace keys, sync, and disconnect | Firm owners, signed in to Tilt themselves |

Changes need the owner's own Tilt sign-in. Tilt Agent can read the status and open the card, and it never changes the connection itself. When the card appears in Claude, ChatGPT, or another connected app, it shows the status with **Open Tilt to make changes**, or **Open Tilt to connect** before the first connection. Other members see the status read-only, with the note **Only firm owners can connect or change the custodian.**

Before an owner first connects or replaces keys, the card asks them to review how Tilt uses brokerage access, the same notice the Connect brokerage card shows before a brokerage connects. Select **Continue** to go on. Until then the card offers no connect form, **Connect another**, or **Open Tilt** button, and **Replace keys** is unavailable. The status, **Sync now**, **Show client accounts**, and **Disconnect** don't wait for it.

## Open the custodian card

In your firm's organization, ask Tilt Agent for it, for example "Open the custodian card so I can replace our keys." You can also ask Tilt Agent for the Connect brokerage card and choose **Alpaca Broker API**, which lists your firm's status.

![Connect brokerage card searched for Alpaca, showing one row, Alpaca Broker API, with the status Connected.](https://mintcdn.com/tilt/z0m5WcpOgLMjZzUt/images/advisor/custodian-picker-row.jpg?fit=max\&auto=format\&n=z0m5WcpOgLMjZzUt\&q=85\&s=03efc47b35a54c2d82ec98f9d3c084ff)

In a firm organization, the Connect brokerage card lists Alpaca Broker API with the firm's status.

| Row status | What it means |
| - | - |
| No label | Nothing is connected yet, and you're an owner. Choose the row to connect. |
| **Not connected** | Nothing is connected yet. A firm owner can connect it. |
| **Connected** or **2 connections** | Every connection is working. |
| **Needs attention** | At least one connection stopped working. Open it to see the custodian's message. |
| **Sign in again** | The firm signed you out after a period of inactivity. [Sign in to the firm again](/advisor/inactivity-logout#sign-in-to-the-firm-again). |
| **Status unavailable** | Tilt couldn't read the status. Open the row to try again. |
| **Unavailable** | You can't see this firm's custodian. Hover over the row for the reason. |

## Get the keys from Brokerdash

Create the API keys in Alpaca's Brokerdash before you connect.

1. Sign in to the Brokerdash of the environment you want to connect: sandbox or live. Keys work only in the environment they were created in.
2. Create API credentials that use a client secret.
3. Choose custom access: read and write for Accounts and Trading, and read only for Data and Reporting. For sandbox keys, also give Journaling read and write, which **Deposit paper funds** uses to move practice cash into client accounts. Give no access to the other areas. Tilt can check only what the keys read before it saves them, so keys without write access still connect but fail later, when Tilt sends a trade or deposits paper funds.
4. Copy the client ID and the client secret. Brokerdash shows the secret once.

Have two more values ready: your firm's correspondent code, and the ID of the firm's sweep account, the Alpaca account that holds the firm's cash. Note the expiry date you set on the keys.

## 1. Connect the firm

1. Choose **Sandbox** or **Live** under **Environment**.
2. Enter the **Correspondent code**, **Client ID**, **Client secret**, and **Firm sweep account ID**.
3. Enter **Keys expire on** if the keys have an expiry date. **Enabled account types** is optional.
4. Select **Connect firm**.

![Connect form with an Environment switch set to Sandbox, fields for Correspondent code, Client ID, Client secret, Firm sweep account ID, Keys expire on, and Enabled account types, and Cancel and Connect firm buttons.](https://mintcdn.com/tilt/z0m5WcpOgLMjZzUt/images/advisor/custodian-connect-form.jpg?fit=max\&auto=format\&n=z0m5WcpOgLMjZzUt\&q=85\&s=5d1029c6a1ff6b9f7d7c95019873ea76)

The connect form. The keys go from the card to Tilt and are never added to the chat.

Tilt checks the keys before it saves anything. With the keys, it reads the firm's account list, the sweep account, and the sweep account's balances. It refuses keys that can't read trading accounts, keys of a firm that is already connected to Tilt in the same environment, and keys that reach client accounts another Tilt connection holds. Each environment of a custodian firm connects to one Tilt organization only. When Tilt refuses the keys, the card shows the reason.

Enter keys only in the card. Don't paste them into a chat message.

To connect a second firm, or the same firm's other environment, select **Connect another**. Connecting the same firm in the same environment again is refused; [replace its keys](#3-replace-the-keys) instead.

## 2. Read the connection

Each connection is titled with its correspondent code and environment, with a **Connected** or **Needs attention** badge.

![Custodian connections card for the CLA1 Sandbox connection, marked Connected. It lists Custodian Alpaca Broker API, Client ID ends in Q7XZ, Key expiry Jan 20, 2027, Last synced, Connected on, and Client accounts 3 with 3 linked to a client, followed by Replace keys, Sync now, Show client accounts, Disconnect, and Connect another.](https://mintcdn.com/tilt/z0m5WcpOgLMjZzUt/images/advisor/custodian-card-connected.jpg?fit=max\&auto=format\&n=z0m5WcpOgLMjZzUt\&q=85\&s=768946a23af57e4ba130ffc9487ff3d6)

A working sandbox connection for a made-up firm, as a firm owner sees it.

| Field | What it shows |
| - | - |
| **Custodian** | The custodian the connection uses. |
| **Client ID ends in** | The last characters of the client ID, so you can match the keys in Brokerdash. |
| **Key expiry** | The expiry date the owner entered, or **Not set**. Once the date passes, it reads **Keys expired on** and the date. |
| **Keys replaced on** | The day the keys were last replaced. It appears after the first replacement. |
| **Last synced** | When Tilt last read the firm's client accounts, or **Not synced yet**. |
| **Connected on** | The day the firm connected. |
| **Client accounts** | How many client accounts the connection holds, and how many of them are linked to a client. |

Tilt doesn't send a reminder before the keys expire. Set your own reminder to replace them ahead of the date.

When a connection needs attention, the card shows **This connection stopped working.** with the custodian's message. An owner fixes it with **Replace keys** in that warning.

## 3. Replace the keys

Replace the keys before they expire, or when the connection needs attention.

1. Create new keys in Brokerdash, in the same environment as the connection.
2. Select **Replace keys**.
3. Enter the **New client ID** and **New client secret**.
4. Enter **New keys expire on**. Leaving it blank clears the current expiry date.
5. Select **Replace keys**.

![Replace keys form under the connection's details, explaining that the new keys come from Brokerdash's Sandbox environment and that Tilt keeps the current keys if the check fails, with New client ID, New client secret, and New keys expire on (optional) fields, the hint Leave it blank to clear the current expiry date, and Cancel and Replace keys buttons.](https://mintcdn.com/tilt/z0m5WcpOgLMjZzUt/images/advisor/custodian-replace-keys.jpg?fit=max\&auto=format\&n=z0m5WcpOgLMjZzUt\&q=85\&s=2e70614fc506b80f4800d460a891f584)

Replacing the keys of the CLA1 Sandbox connection.

Tilt checks the new keys the same way it checks a new connection, and keeps the current keys if the check fails. Once Tilt accepts the new keys, revoke the old ones in Brokerdash, since Tilt can't revoke keys at Alpaca. A connection's environment never changes; to move from sandbox to live, connect the live environment with **Connect another**.

## 4. Sync and review client accounts

**Sync now** reads the firm's client accounts from Alpaca. When it finishes, the card says how many client accounts synced, or that the sync was incomplete or failed. Only firm owners can start a sync.

**Show client accounts** lists each client account with its **Client** column, **Linked** or **Not linked**, and a **Custodian restriction** column that shows why Alpaca limits trading in the account, or **None**. Every member who can see the connection can open the list. You can also ask Tilt Agent which client accounts a connection holds.

## 5. Disconnect

Select **Disconnect** to see what disconnecting would do, with your firm's numbers, before anything changes.

![Disconnect CLA1 Sandbox warning: 3 of its 3 client accounts are linked to clients, disconnecting takes every client account out of its portfolio groups and closes its holdings in Tilt, and reconnecting creates new client accounts so the links to clients don't come back. No approved trades are waiting to be sent. No orders are waiting to reach Alpaca Broker API. Tilt deletes the stored keys; revoke the keys in Brokerdash too. Below are a Type CLA1 to confirm field and Keep connection and Disconnect buttons.](https://mintcdn.com/tilt/z0m5WcpOgLMjZzUt/images/advisor/custodian-disconnect.jpg?fit=max\&auto=format\&n=z0m5WcpOgLMjZzUt\&q=85\&s=42530845b5878f16a1a1bcae968e3a7e)

The disconnect warning. Disconnect stays unavailable until the owner types the correspondent code.

Disconnecting:

* takes every client account out of its portfolio groups and closes its holdings in Tilt. Reconnecting later creates new client accounts, so their links to clients don't come back.
* leaves approved trades that weren't sent yet approved, but they can't be sent.
* marks orders that never reached Alpaca as failed. Orders Alpaca already has are left as they are.
* deletes the keys Tilt stored. Tilt can't revoke keys at Alpaca, so revoke them in Brokerdash too.

To go ahead, type the connection's correspondent code and select **Disconnect**. **Keep connection** closes the warning and changes nothing.

## Signed out of this firm

If the card says **Signed out of this firm**, your firm signed you out after a period of inactivity. [Sign in to the firm again](/advisor/inactivity-logout#sign-in-to-the-firm-again), then reopen the card.

Tilt keeps a record of each connect, key replacement, and disconnect, without the keys. See [History coverage](/advisor/history-coverage) for what Tilt records.


# Configure automatic corporate-action restrictions
Source: https://docs.tilt.now/advisor/corporate-action-restrictions

Set firm rules that pause trading or exclude portfolio targets around corporate actions.

Configure firm rules so Tilt adds restrictions when a relevant corporate action affects your organization. These rules change optimization inputs and do not submit trades. Account and model allowances still apply; see [Settings and rules](/advisor/configuration-and-rules#3-add-conditional-restrictions-or-bounds).

## 1. Open the firm's restrictions

1. Click **Firm** in the left sidebar.
2. Click **Setup**, then **Constraints**.
3. Find **Automatic corporate-action rules**.

Check that you are editing the intended firm's settings. These rules apply across the organization.

## 2. Enable the recommended rules

Turn on **Automatic corporate-action rules**. Tilt selects the recommended rules for all supported event types:

| Event | Recommended action | Timing |
| - | - | - |
| Delisting | **Exclude portfolio targets (No-hold)**. Excludes the ticker from optimized holdings while allowing an exit, unless another restriction blocks trading. | Immediate, until the effective date at midnight UTC. |
| Other enabled event types | **Pause trading (No-trade)**. Blocks buys and sells, including an exit from an existing position. | Immediate, until the effective date at midnight UTC. |

If both No-hold and No-trade apply to a ticker, No-trade takes precedence.

## 3. Adjust an event rule

Open **Advanced overrides**. Clear an event's checkbox to stop creating new restrictions for that event type. To change an enabled event, click **Edit** beside it.

1. Choose **Action**: **Pause trading (No-trade)** or **Exclude portfolio targets (No-hold)**.
2. Choose **Start**: **Immediately** or **Days before effective date**. For days before, enter a whole number of at least 1 in **Calendar days before effective date**.
3. Review **End**. Rules end on the **Corporate-action effective date** at midnight UTC, at the start of that date. For No-hold, you can choose **No end date**, which excludes portfolio targets immediately until you remove the restriction.

![Automatic corporate-action rules enabled, with Advanced overrides open and the delisting editor showing Exclude portfolio targets (No-hold), Immediately, and Corporate-action effective date.](https://mintcdn.com/tilt/Hfny0uGbVAFhrCTK/images/advisor/corporate-action-restrictions.png?fit=max\&auto=format\&n=Hfny0uGbVAFhrCTK\&q=85\&s=1594fb00b9615ce639935c263ca9f112)

Advanced overrides shows the action, start, and end for each enabled event. This delisting rule uses the recommended immediate No-hold exclusion until the effective date.

Timing follows corrections to the corporate action's effective date. If a saved No-trade rule shows legacy duration-based timing, choose a **Start** timing to replace it with a rule that ends on the effective date.

## 4. Apply and verify

Review the queued firm changes and click **Apply firm changes**. Refresh the page and reopen **Constraints** to check the saved event selections, actions, and timing.

Changing a default affects new restrictions. Existing restrictions keep their saved terms, including when you turn off an event or the main switch. Turning the main switch back on restores the recommended defaults for all event types; review any overrides before applying.

To end an existing automatic restriction, find its **Corporate action** row under **No-hold tickers** or **No-trade tickers** on the same page. Click **Remove**, then **Queue removal**, and apply the queued firm change. Tilt preserves manual and overlapping restrictions and will not reapply the removed event's restriction.

## 5. What happens when a corporate action affects your firm

A corporate action affects your firm when its ticker is held in one of your client accounts, or is in an index those accounts use. For each enabled event type, Tilt then adds a restriction under **No-hold tickers** or **No-trade tickers** on the firm's **Constraints** page. The row carries a **Corporate action** badge and the start and end your rule sets. A restriction whose start date is still ahead shows as scheduled; it applies to optimizations from its start time.

Tilt keeps the restriction in step with the event:

| If the event | Tilt |
| - | - |
| Moves to a new effective date | Moves the restriction's dates to match. |
| Is cancelled or rejected | Ends the restriction. |
| Reaches the end your rule sets | Ends the restriction and moves it to **History** at the bottom of the list. A No-hold rule with **No end date** stays until you remove it. |

The restriction changes optimization inputs only. Tilt does not place or cancel trades when it starts or ends.

## 6. Read the alerts

Tilt sends two kinds of corporate-action alerts. Both appear under **Alerts** in the left navigation.

| Alert | Example title | What it says | Opening it |
| - | - | - | - |
| An upcoming corporate action affects your firm | *Pause XYZ trades for 3 accounts* | The firm, the ticker, and how many client accounts and indexes are exposed. | Starts a Tilt Agent chat to review the event. |
| An automatic restriction starts or ends | *XYZ firm-wide restriction activated* | Whether it is a trading pause or a portfolio-target exclusion, and that account and model allowances still apply. It also notes that the alert places no trades. | Opens the restriction's row on the firm's **Constraints** page. |

To choose which firms you get these alerts for, open **Settings**, then **Alerts** under **Personal**. Under **Corporate action alerts**, select the organizations.

After changing restrictions, follow the [rebalance review workflow](/advisor/review-rebalance) when you are ready to review and submit trades.


# Daily briefing
Source: https://docs.tilt.now/advisor/daily-briefing

Understand the daily view of advisor book coverage, drift, breaches, and work that needs attention.

**Daily briefing** gives you a dated view of the accounts in your advisor organization that need review. It brings book coverage, drift status, breached monitoring rules, and possible next steps into one Tilt Agent chat. Open a book-wide chat and choose **Daily briefing**, or ask Tilt Agent for your advisor daily briefing.

Tilt Agent uses today's completed book report when one is available. Otherwise, it starts today's calculation. That calculation can save monitoring optimization results as proposals for review. The briefing does not approve a proposal or place a trade.

[How monitoring policies work](/advisor/monitoring-explained) explains the drift and tracking error measurements behind the report's warnings and breaches.

## Read the Client book

The **Client book** card shows the report date and how many accounts were evaluated. Its status badges count evaluated accounts as **breached**, **drifting**, or **holding**. **Total AUM** comes from the organization's aggregate holdings. **Needs attention** includes accounts with drift, data quality, or account health reasons that warrant a closer look; it can exceed the breached count.

**Accounts covered** shows the evaluated count against the total when coverage is incomplete. A note below the figures can identify gaps such as unevaluated households, unavailable clients, stale account data, or skipped accounts. The card can also list skipped accounts and their reported reasons. Check this coverage before treating the summary as a review of the whole book; a skipped account has no evaluated drift status in that report.

![October 8 Client book showing 16 of 18 accounts evaluated, seven breached, one drifting, eight holding, ten needing attention, and two skipped Priya Kim accounts.](https://mintcdn.com/tilt/Nj1SDGdRgiYweBVF/images/advisor/evergreen-daily-client-book.jpg?fit=max\&auto=format\&n=Nj1SDGdRgiYweBVF\&q=85\&s=f5cb7be8afe427aa909b4950b187e8d4)

The dated Client book card shows account status, coverage, AUM, and accounts needing attention.

## Examine today's breaches

When at least one account breached a monitoring rule, **Today's breaches** shows the affected clients and accounts. The selected account displays a leading breach, followed by a table of rule categories, measured values, limits, rule sources, and statuses. Use **Next** and **Previous** to move through the breached accounts. **Inspect account** opens a closer review; **Review monitoring rules** shows the rules that apply to that account.

The example below shows a measured value alongside its organization rule limit. Compare the value with the limit and inspect the named account before deciding what to do. The card appears only for breached accounts; other accounts needing attention can still appear in the **Client book** count.

![Today's breaches for Maya Patel's synthetic Revocable Trust, showing U.S. Large Cap, total drift, international developed, and cash measurements beside their organization rule limits.](https://mintcdn.com/tilt/Nj1SDGdRgiYweBVF/images/advisor/evergreen-daily-breaches.jpg?fit=max\&auto=format\&n=Nj1SDGdRgiYweBVF\&q=85\&s=9dc45a7a7123b917978880b32a894ac8)

The breach card shows the selected account's measured values beside the limits of its monitoring rules.

When the report includes **Model drift details**, inspect **Off-model holdings** and **Drift basis** as well as the sleeve breaches. Off-model holdings measures the share of eligible ticker holdings outside the model. The detail also identifies manual assets and legacy non-tradable value excluded from model drift. Those excluded values remain in account AUM, so the drift basis can differ from the account's total value. Use the listed off-model tickers to investigate the positions involved.

## Choose a follow-up

**Next steps** offers follow-ups based on the current report. Depending on the results, you can review attention accounts, check optimizations or rebalance proposals, review book health, or explore exposures. Select a follow-up to continue in Tilt Agent, then inspect the account or proposal it opens. [Review a rebalance](/advisor/review-rebalance) explains the separate proposal and trade decisions.

If today's completed report is still unavailable, Tilt Agent asks you to retry the briefing. Wait for a current result before relying on its counts or breach detail.

## Review proposed orders

If the briefing offers **Check rebalance proposals**, it opens a **Daily optimization review** for the breached accounts. The review shows its evaluation date and separates accounts that are **Ready**, **Needs attention**, or are **Approved**. Each account row shows its status, proposed order count, turnover, and estimated cost. Use **Review details** to open an **Account proposal** before selecting it for approval.

The account proposal shows turnover, transaction cost, estimated tax due, cash buffers, and the proposed orders. Use the order list's **Next** and **Previous** controls to review every order when the list spans pages. Check the account, order sides, tickers, and amounts alongside the metrics; a summary count alone does not show the full proposal.

![Account proposal marked Ready, with turnover, transaction cost, estimated tax, cash buffers, and a paginated table of proposed buy orders.](https://mintcdn.com/tilt/pbyPja39Op4jLjys/images/advisor/daily-briefing-account-proposal.png?fit=max\&auto=format\&n=pbyPja39Op4jLjys\&q=85\&s=46b8b1a208aa89a8d8f703c1a6491837)

The Account proposal shows optimization metrics and proposed orders before batch selection.

## Decide whether to approve proposals

Select only the ready proposals you have reviewed. You can select an account from its detail view or the review table; **Select all ready** includes every eligible proposal. Accounts needing attention cannot be selected until their blocker is resolved.

When the selection includes accounts eligible for custodian submission, the action reads **Approve and send…**. Review the confirmation's accounts, custodian, buys, sells, and order count before confirming **Send**. Confirming records approval and submits the eligible orders. Accounts without a custodian account are approved only; no trades are placed for those accounts.

For an approval-only selection, the action reads **Approve…**. Its confirmation states that approval is recorded and no trades are placed. After confirming either action, inspect the receipt and any order statuses. Submission does not establish that orders filled. [Review a rebalance](/advisor/review-rebalance) covers how to inspect a saved proposal before any trade decision.


# History coverage
Source: https://docs.tilt.now/advisor/history-coverage

Recorded actions, attribution, and the limits of History for supervision.

History is a view of the firm's audit log, on each object's page and across the whole firm on the **Firm** page. Entries record an action, when it happened, who acted, the objects concerned, and a reference to what caused it. Settings entries include changed fields with before and after values.

Entries cannot be edited or deleted. A later change creates a new entry; it does not rewrite the earlier record.

For instructions on finding and reading entries, see [See who changed an account and why](/advisor/see-who-changed-an-account).

## Reading operations and routine activity

History groups records from the same recorded operation into one row. Choose **View operation** to read the individual changes, including each account's before and after values. The counts cover records on the timeline you are viewing. Older records without an operation reference stay separate.

A portfolio group rename creates a client entry without a settings entry for each account. Changes to targets, construction settings, or membership retain the affected accounts' settings evidence, including departures. A model edit does not create copies on every assigned account.

History hides automation runs that changed nothing by default. Select **Include routine activity** to see them. Tilt retains these records; the filter does not delete them. Failed runs remain visible. A grouped row reports recorded failures without claiming that every other step succeeded. Approval, sending, and completion remain separate facts; sharing a conversation or background job does not make them one operation.

## Recorded actions

Each object's page shows entries for that object. To review a model change, for example, open the model's History rather than a client's History, or find it in the firm's History, which covers the firm's objects.

| Area | Recorded outcomes |
| - | - |
| Firm Security | Changes to the firm's [inactivity logout](/advisor/inactivity-logout) and its [passkey and two-step rules](/advisor/require-passkey-or-two-step-sign-in), with the old and new values. A member adding or removing their own sign-in method for the firm, and an owner or Tilt support resetting a member's methods. Entries count methods by kind and never include a phone number, a code or a secret. |
| Firm settings | Order policy, factor values, default customization, risk-model inputs, available investments, and corporate-action restrictions. Release-policy revisions retain the saved rules; accepted trade releases reference the policy revision and evaluation used. |
| Account settings | Tax account type, external ID, metadata, reporting benchmark, assigned model, account customization, and sleeve settings. Account-linking setup changes and portfolio target imports also record affected account settings. |
| Models and sleeves | Creation and deletion, settings and allocation changes, imported configurations, draft and deployed status, and sleeve archiving and restoration. |
| Monitoring | Explicit firm, model, and account monitoring rules, including removal. Monitoring-only changes have their own entries. |
| Tax and legacy allocations | Client and household gains budgets; realized-gains additions, corrections, and confirmations; accepted legacy allocations, removals, and target transitions. |
| Clients, accounts, and households | Creation, deletion, restoration, name changes, identity linking, and household joins and departures. A departure stays in the former household's History, including when its last member leaves. |
| Positions and custody | Manual position and tax-lot replacements, imported position changes, account links, trading stops and restarts, account-opening outcomes and confirmed follow-ups, direct order status changes, deposits, and currency conversions. Price refreshes do not create position-change entries. |
| Firm access | Invitations, membership role changes and removal, and grants or revocations of advisor access to a household. |
| Trade proposals | A proposal becoming ready for review, failure to produce a proposal, approval, and marking a proposal executed. |
| Custodian trade instructions | Approval of trades for the custodian and subsequent instruction status changes, including sending, completion, partial sending, refusal, and cancellation. |
| Changes drafted by Tilt Agent | A saved change proposal being created, applied, discarded, or not applied because the saved value changed first. The underlying settings change has a separate entry when applied through a recorded workflow. |
| Tilt actions | Creation and duplication, saved edits through the Tilt editor (including applied analysis results), publication, deletion of an unpublished draft, archiving, restoration, rationale changes, and scheduled rebalances. Separate analysis-completed and re-analysis-completed entries are not emitted by the current workflows. |
| Automation runs | Finished firm automation runs, including successful runs, failed runs, and runs that changed nothing. Entries reach subscribed objects and their containing client or household where applicable. Select **Include routine activity** to see runs that changed nothing. |
| Automation setup | Creation, instructions, schedule, subscribed objects, pause, resume, and deletion. |
| Agent guidance | Changes to enabled guidance packs for a person in the organization, including replacements. Entries retain the selected packs and their guidance at the time. Repeated onboarding checks and pending invitations do not create separate entries. |
| Connected apps | Tool permission changes, including **Always allow**, **Needs approval**, and **Blocked**; approval and denial taps on tool-call cards; whether an approved call received a response, failed, went unconfirmed, or was not sent; calls sent under Always allow; and calls from a connected app's view that the app does not mark read-only. |
| Custodian connection | Connecting the firm's custodian, replacing its API keys, and disconnecting it. A disconnect is also recorded when the owner who last entered the keys leaves the firm, loses the owner role, or deletes their Tilt account, and no other owner remains to take the connection over. Entries do not include the keys. |

Approval and execution are separate outcomes. An approval entry alone does not establish that orders were sent or filled. Check the instruction and order statuses when reviewing trading activity.

Connected-app entries concern the firm, so they do not appear in an individual account's or model's History. An approval does not prove the call was sent or completed.

## Who acted and why

| Actor | What History shows |
| - | - |
| A firm member | The person's recorded email address. |
| A Tilt Agent run | **Tilt Agent**, with the person it acted for. |
| The system | **Tilt**. |
| Tilt support | **Tilt support**, for a reset of a member's sign-in methods that Tilt support made. |

Membership role changes, removals, and invitation entries also name the affected member or invitee by the email recorded at the time. Later email changes do not rename those entries. Older entries may not include this label.

For linked clients and household members outside the firm, History uses **Linked client** or **Household member** instead of their email address. Their identity remains subject to the access controls for identity links and household membership.

Each entry references the request, conversation message, reviewed change proposal, automation run, or scheduled job that caused it. This reference may not include a written investment rationale. You can open a linked conversation if you have access; the audit entry itself does not contain the transcript.

Entries keep object names as recorded at the time of the event, after the change. A rename therefore uses the new name, with old and new values in its change details when recorded. Later renames, deletions, and household moves do not rewrite these saved names. Older entries without saved names can use current names or a generic label such as **An account**.

Availability changes and index decisions identify the investment by its recorded name. Older availability entries without a saved name show the recorded investment ID. Client and household gains-budget entries identify the budget year, including when someone removes a budget. These details appear in History rows and expanded operations.

Automation setup entries identify the automation by its saved name, or its ID when unnamed. Connected-app entries identify the app and tool. These labels use the values recorded at the time, including in expanded operations.

## Events for automated reviews

Ask Tilt Agent to watch for recorded changes, such as model and sleeve settings updates, and post summaries in chat. Follow [Review changes with an event automation](/tilt-agent/review-changes-automation) to choose what to watch and what to report.

## Activity outside History

Tilt records saved changes, decisions, and connected-system actions that affect clients, accounts, households, or the firm's rules, whether a person, Tilt Agent, or the system acts. The limits below apply to that coverage.

Opening pages, reading data, previewing changes, and editing unsaved drafts do not create entries. Neither do retries without a new outcome, personal layout changes, or thumbs-up and thumbs-down chat feedback. Inactivity sign-outs, signing in to a firm again, and passkey or two-step checks do not create entries either, though changes to the firm's sign-in settings and to members' sign-in methods do. A clarification in chat can lead to a saved change without becoming a separate History entry. Tilt records saved change proposals and finished automation runs, including runs with no changes.

## Coverage limits

Connected-app records distinguish permission, approval, and outcome:

| Area | How to interpret the entry |
| - | - |
| Connected-app permissions | A person's connection and tool permissions belong to the firm where they connected the app. That firm receives the change entry. |
| Connected-app outcomes | An approval entry alone does not establish that Tilt sent the call. Check the call's outcome entry. Always allow and view-call entries record the send attempt, not the provider's confirmed result. An app's successful response does not prove the resulting state in that app. |

Account settings entries do not provide a history of market-value updates. Use position-change entries and custodian records when reviewing holdings. Some firm-level actions have no separate account, client, household, or model target and will not appear on those pages.

## Using History for supervision

Tilt delivers some entries, such as change-proposal reviews, connected-app activity, and automation outcomes, separately from the original save. History therefore cannot guarantee an entry for every completed action.

An empty History or a missing row does not establish that no action occurred. Compare the object's saved state, the source conversation when available, and proposal or custodian order records as appropriate. History's append-only entries do not by themselves establish a regulatory retention period or that your firm's recordkeeping obligations are met.

When reviewing an allocation decision months later, check both the account's History and the relevant model's History. A model change is not copied into every assigned client's or household's History. Proposal records retain captured trading inputs and reviewed trade details; accepted release entries reference their policy and evaluation evidence. A cause reference does not guarantee that the advisor's investment rationale was written down.

Entries are recorded from each workflow's introduction of audit recording onward; History does not backfill all earlier activity. Retain the additional records your firm's supervision process requires.


# Set an inactivity logout for your firm
Source: https://docs.tilt.now/advisor/inactivity-logout

Sign people out of your firm after a set time without activity. They get back in to that firm with their usual sign-in.

An inactivity logout signs a person out of your firm after a set time without activity in Tilt. It protects a screen that someone walked away from. It applies to your firm only: the person's personal workspace and their other organizations stay signed in.

## 1. Choose the timeout

Open **Settings > Security**. **Security** appears under **Organization** in the Settings menu while you're in your firm. You can also open **Firm**, then **Setup** > **Sign-in security**. Only an organization owner can change the setting.

Under **Inactivity logout**, choose **Off**, **15 minutes**, **30 minutes**, or **1 hour** in **Sign out after**, then select **Save changes**. Every firm starts at **Off**.

![Settings with Security selected under Organization. The Inactivity logout group shows Sign out after set to Off, with its list open on Off, 15 minutes, 30 minutes, and 1 hour. The open list partly covers the Save changes button. Below is a History group with an Open History button.](https://mintcdn.com/tilt/JTLmWmQyCLgkRSaY/images/advisor/security-inactivity-logout-owner.jpg?fit=max\&auto=format\&n=JTLmWmQyCLgkRSaY\&q=85\&s=eec715ca036645f7569c326749b59b74)

An owner choosing the timeout.

Members who aren't owners see the setting read-only, with **Only an organization owner can change this.**

![Inactivity logout group showing Sign out after with the value 15 minutes and the note Only an organization owner can change this. There is no list to choose from and no save button.](https://mintcdn.com/tilt/JTLmWmQyCLgkRSaY/images/advisor/security-inactivity-logout-read-only.jpg?fit=max\&auto=format\&n=JTLmWmQyCLgkRSaY\&q=85\&s=b94299c7e8b27d09dbde7901748cc68d)

What other members see once the owner saves 15 minutes.

The timeout counts from each person's last activity. Someone who has already been away for longer than the timeout you save is signed out of the firm when they come back.

Choosing **Off** also lets everyone the firm signed out for inactivity open it again without signing in again. A firm that also [requires a passkey or two-step sign-in](/advisor/require-passkey-or-two-step-sign-in) still asks for that.

## 2. Check the change in History

Each save adds an entry to the firm's History. Select **Open History** on the Security page, or open **Firm** in the left sidebar, then **History**. The entry reads **Changed settings** and lists the old and new timeout. Its **About** column says **Security**, its **Kind** column says **Firm**, and **By** names the owner who saved it. [See who changed an account and why](/advisor/see-who-changed-an-account) explains each column.

![Firm History row at 11:31 AM: About Security, Kind Firm, What happened Changed settings, Inactivity logout Off → 15 minutes. The By column is blurred and Source shows a dash.](https://mintcdn.com/tilt/JTLmWmQyCLgkRSaY/images/advisor/history-inactivity-logout.jpg?fit=max\&auto=format\&n=JTLmWmQyCLgkRSaY\&q=85\&s=770021921ef3f5537167b8062fcf0083)

The History entry for turning the inactivity logout on. The owner's email address is blurred.

## What counts as activity

The rest of this page describes what everyone in the firm sees once the timeout is on, owners included.

Typing, clicking, scrolling, and tapping in a Tilt tab count as activity. Moving the pointer without clicking doesn't count, and neither does a page that updates on its own.

Activity anywhere in Tilt in the same browser counts, including your personal workspace and your other organizations. Each browser you sign in with keeps its own count. Tilt for Mac keeps its own count too; see [Tilt for Mac](#tilt-for-mac).

A Tilt Agent reply that is still running also keeps the firm open. While a reply you started in the firm runs and a tab of the firm is open, the firm stays open for up to one extra timeout period. With a 15-minute timeout, a long reply can keep the firm open for up to 30 minutes after your last activity.

## Before you're signed out

A minute before the timeout runs out, an open tab of the firm asks **Are you still there?** and counts down. Select **Stay signed in** to keep working. It counts as activity, so the timeout starts again.

![Dialog titled Are you still there? reading Maple Ridge Advisors signs you out after 15 minutes without activity. You'll be signed out in 0:59. A Stay signed in button sits below.](https://mintcdn.com/tilt/JTLmWmQyCLgkRSaY/images/advisor/inactivity-countdown.jpg?fit=max\&auto=format\&n=JTLmWmQyCLgkRSaY\&q=85\&s=432ef2e4ea4bbe2a45a3d0c84b1d9a7a)

The question a minute before a demo firm, Maple Ridge Advisors, signs the person out.

## Sign in to the firm again

When the timeout runs out, Tilt signs you out of that firm only. Your personal workspace and your other organizations stay signed in. A tab open in the firm moves to the firm's sign-in page, which says why you were signed out. Opening the firm later, from another workspace or a new tab, leads to the same page.

Sign in to the firm again the way you usually sign in to Tilt:

| Way | What to do |
| - | - |
| Emailed code | Select **Email me a code**, enter the code Tilt sends to the email address on your Tilt account, and select **Continue**. If the code doesn't arrive, select **Send a new code**. |
| Google | Select **Continue with Google**. It appears when your Tilt account signs in with Google. In Tilt for Mac, Google's sign-in opens in your browser; finish it there and the Mac app signs you in to the firm. |
| Passkey | Select **Use your passkey**. It appears when the firm requires a passkey and you have one for it, and it also counts as the firm's passkey check. **Email me a code instead** stays available. |

![Page titled Sign in to Maple Ridge Advisors again, reading You were signed out of Maple Ridge Advisors after 15 minutes of inactivity, with an Email me a code button and a Choose another workspace link.](https://mintcdn.com/tilt/JTLmWmQyCLgkRSaY/images/advisor/firm-sign-in-again.jpg?fit=max\&auto=format\&n=JTLmWmQyCLgkRSaY\&q=85\&s=08f312c7a9332ddb31b94118f4fe39c7)

The firm's sign-in page after 15 minutes without activity, for an account that signs in with an emailed code.

Tilt opens the firm again on the page you were on. To go somewhere else instead, select **Choose another workspace**.

A firm that also requires a passkey or two-step sign-in asks for it next, because coming back after the inactivity logout always asks again. [Sign in to a firm that requires a passkey or two-step sign-in](/advisor/sign-in-with-passkey-or-two-step) covers those steps.

Signing in to the firm again unlocks it in that browser only. If the firm also signed you out in another browser or in Tilt for Mac, sign in again there too.

## Tilt for Mac

[Tilt for Mac](/tilt-agent/tilt-for-mac) keeps its own count of activity. Working in your browser doesn't keep the firm open in the Mac app, and working in the Mac app doesn't keep it open in your browser. Activity in the Mac app's [page tabs](/tilt-agent/page-tabs) counts for the Mac app.

In the Mac app, **Are you still there?** covers the whole window, page tabs included. When the timeout runs out, the window moves to the firm's sign-in page, and you sign in again there with **Email me a code**, or with **Continue with Google** when your Tilt account signs in with Google. When the firm requires a passkey and you have one for it, Tilt for Mac 1.30.1 or newer also offers **Continue in your browser**: your browser opens so you can use your passkey, and then you're back in the Mac app.

You sign in to Tilt for Mac through your browser. If your browser was already signed out of a firm, or its timeout had already run out there, the firm opens signed out in the Mac app too. Sign in to the firm again in the Mac app.

## What keeps running

The inactivity logout applies to people signed in to Tilt. These keep working while someone is signed out of the firm:

* Automations and other [background jobs](/tilt-agent/background-jobs) in the firm.
* Tilt Agent replies that had already started.
* Apps connected to Tilt, such as Claude or ChatGPT.
* Requests made with a Tilt API key.

## Ask Tilt Agent

Tilt Agent reads your firm's inactivity logout and explains a sign-out. Ask, for example, **"How long can I be away before Tilt signs me out of the firm?"** or **"Why was I signed out?"**

Tilt Agent never changes the setting itself. Ask it to turn the inactivity logout on or change it, and it prepares a review card with the current and new value. Nothing changes until an owner applies the card in Tilt. If you aren't an owner, Tilt Agent names the firm's owners so you can ask one.

Never paste a sign-in code into chat. Enter it on Tilt's sign-in page.


# Models, sleeves, and benchmarks
Source: https://docs.tilt.now/advisor/models-and-benchmarks

Understand target allocations, composite sleeves, account customizations, configurations, implementations, and asset-class exposure.

A sleeve is a reusable investment building block that holds securities or other sleeves. A model portfolio is a sleeve designated for account assignment and model management. Its composition is the same shared investment definition wherever that sleeve is used. Benchmarks and implementations supply the holdings used to express its targets. An account can combine a primary model with additional sleeves and its own settings.

These concepts answer different questions:

| Concept | Question it answers |
| - | - |
| Model portfolio | Which shared sleeve is assigned as the account's primary model and supplies inherited settings? |
| Sleeve | What does this reusable investment building block hold, and at which weights? |
| Benchmark | What reference holdings and weights are used for comparison? |
| Implementation | Which investments can the account use to reach the sleeve's exposure? |
| Asset-class type | How much equity, fixed income, cash, or other classified exposure does the account hold? |

## Composite sleeves hold other sleeves

A sleeve is either a building block or a composite. A building block holds one implementation, such as an ETF, an index, a Tilt, or a single security. A composite holds other sleeves, each with a target share. A model's tree of sleeves can be up to ten levels deep, and each of the model's own sleeves can hold up to 500 sleeves below it. A sleeve inside several composites counts once for each composite that holds it.

![Tree of Global 80/20: US Equity 50% holds US Large Cap 70%, US Mid Cap 20%, and US Small Cap 10%; US Large Cap holds US Large Growth 55% and US Large Value 45%. US Large Growth is 19.25% of the model.](https://mintcdn.com/tilt/4B6KGiVWkSQCWWf9/images/advisor/composite-sleeves.svg?fit=max\&auto=format\&n=4B6KGiVWkSQCWWf9\&q=85\&s=a4312699268088b786d87dea130f9b96)

Global 80/20, a model in the made-up Northwind Family Office practice. US Equity and US Large Cap are composites; the rows indented under them are what they hold.

Each sleeve has two weights:

| Column | Meaning | US Large Growth in Global 80/20 |
| - | - | - |
| Target % | The sleeve's share of the sleeve that holds it, or of the model for a top-level sleeve | 55% of US Large Cap |
| Model % | The sleeve's share of the whole model | 50% × 70% × 55% = 19.25% |

Multiply the Target % values along a sleeve's path to find its Model %.

If a ticker has a 10% weight within US Large Growth's reference basket, that sleeve contributes 1.925% of the whole model to the ticker. If another building block also contains it, its model weight includes that sleeve's contribution too. Count building blocks once; adding a composite to the sleeves it holds double-counts its allocation.

## Accounts can combine a primary model and other sleeves

An account can inherit its primary model's allocation or set its own top-level portfolio weights. For example, the Chen Household IRA could hold Global 80/20 at 90% and a Gold sleeve at 10%. Global 80/20 remains the primary model and supplies inherited settings. The weights and additional sleeve belong to this account; the shared model and Gold definitions stay unchanged.

Multiply through the account's portfolio weight to find each sleeve's account share. US Equity at 50% of Global 80/20 contributes 45% of an account holding that model at 90%. If a ticker appears in both the primary model and an additional sleeve, its target includes both contributions.

Portfolio weights must total 100%, with a positive weight in the primary model. Primary designates the model assignment and inherited settings; it does not require the largest portfolio weight. [Set account portfolio weights](/advisor/tailor-account#set-account-portfolio-weights) covers editing and returning to the inherited allocation.

The saved portfolio supplies optimization targets. Proposed holdings can differ because the optimizer considers current holdings, taxes, costs, and constraints. Saving weights places no trades; [review a rebalance](/advisor/review-rebalance) before sending orders.

## Exposure and implementation are related choices

A sleeve can draw on a Tilt, a published Tilt index, a standard index, an ETF, or a single security. For a supported standard index, enabling direct indexing uses constituent weights; otherwise its implementation can use the benchmark ETF and configured ETF alternatives. Direct indexing is not supported for a single-security sleeve. While a model, a composite, or an account direct indexes a building block, its holding can change only to one that supports direct indexing; [Change what a building block holds](/advisor/build-model-portfolio#change-what-a-building-block-holds) shows where to turn it off first.

An eligible reusable sleeve's **Default direct indexing** supplies the starting choice when you add it to a model or composite. Each placement saves its own choice, so an explicit off setting wins over an on default wherever direct indexing is editable. Changing the reusable default leaves existing placements and account overrides unchanged. Custom indexes stay direct indexed in both placement pickers; Tilt sleeves stay direct indexed in the model picker. [Set the sleeve default](/advisor/build-model-portfolio#set-the-direct-indexing-default-for-a-reusable-sleeve) before adding it to more models or composites.

An account's implementation settings can change how it reaches the allocation. The model's sleeve name alone does not tell you which securities will be held. Inspect the effective sleeve structure, implementation, alternatives, and restrictions before comparing the account with its target. [Build a model portfolio](/advisor/build-model-portfolio) covers creating and assigning that structure.

## A reference is not the current portfolio

Current holdings describe what the account owns. Target holdings describe the allocation it is trying to reach. Proposed holdings describe the optimizer's candidate after trades. A benchmark provides the reference for a comparison.

Ask which reference a metric uses. Sleeve drift compares attributed current sleeve weights with sleeve targets. Ex ante tracking error measures modeled active return risk against reference weights. Neither metric is simply the difference between current and proposed holdings.

When a ticker appears in more than one sleeve, Tilt splits its current weight across those sleeves in proportion to what each contributes to the target. The split is for monitoring; the brokerage holds one position. Configured ETF alternatives count toward their sleeve too, so an account that holds an allowed alternative still fills that sleeve.

## Where a Tilt's tickers count

A Tilt set on a sleeve has its own row under that sleeve in monitoring. The Tilt's tickers count toward that row, and each sleeve beneath it counts its own tickers.

Take an Equities composite that holds US Large Cap at 70%, direct indexed, and a Small Cap basket at 30%, with Quality Leaders +10% set on Equities. On a model that holds only Equities, an account's **Optimization** tab lists these rows:

| Row | Target |
| - | - |
| Equities | 100% |
| US Large Cap | 63% |
| Small Cap basket | 27% |
| Quality Leaders Tilt | 10% |

US Large Cap's tracking error compares its holdings with its index's tickers, and the Small Cap basket's compares them with the basket. The Quality Leaders row compares the Tilt's tickers with the Tilt. A ticker that US Large Cap holds and Quality Leaders adds counts in both rows, each with its share.

A Tilt set on one sleeve, such as US Large Cap alone, has its row under that sleeve. Drift limits apply to the model's top-level sleeves. The rows beneath them show target and current weight for review.

The account's **Overview** shows the top-level rows, and a row beneath them only when it is past a warning or a limit. The rows come from the nightly drift check, so a change to a model or an account shows there after the next check.

## Measurement benchmark

A sleeve's benchmark, in the table above, supplies the holdings the sleeve builds from. A measurement benchmark is a separate choice: what Tilt measures a model's or an account's results against. Setting one doesn't change holdings, trades, or optimization.

| Set on | Where | What uses it |
| - | - | - |
| A model | The model's Setup, under Measurement benchmark. Choose Set custom benchmark or Change and pick a benchmark from the catalog. Reset custom benchmark removes it. | The model's Historical performance and Estimated risk, and the model's accounts that have no measurement benchmark of their own. |
| An account | The account's Setup, under Measurement benchmark. Choose Set custom benchmark or Change benchmark and build a named, fixed-weight basket. Without one, the account uses its model's and shows Inherited from model. | The account's risk and tracking error measurements, and the benchmark line on its [Performance](/advisor/account-performance) chart. |

The model page shows Historical performance above the model's allocation: a growth of 100 chart of the model's current saved targets, against its measurement benchmark when it has one, over 1 month to 5 years. Its figures are the model's annualized return, the benchmark's return, volatility, max drawdown and, with a benchmark, tracking error. Tilt buys today's targets at the period's first close and holds them without rebalancing, with no fees, taxes, trading costs or cash flows, so the chart is a hindsight illustration of the current targets. Estimated risk, in the same section, forecasts tracking error and volatility from the risk model and doesn't depend on the chart's period. An account's actual return is on the account's own page: see [Account performance](/advisor/account-performance).

Without a measurement benchmark, Historical performance still charts the model's current targets, with its return, volatility and max drawdown. It has no benchmark line and no tracking error, and the button beside the period reads Set benchmark, which opens the model's Setup. When Tilt doesn't have the prices for a period, the section says so and shows nothing in place of the missing data. Choose another period or benchmark.

Tilt Agent can set, change or clear a model's measurement benchmark too. Name the model and the benchmark, for example:

> Measure the Growth 70/30 model against SPY.

Check the model's Setup afterward to confirm the saved benchmark.

## Asset-class type is a separate view

Sleeves describe model structure. Asset-class types describe classified exposure, including equity, fixed income, commodity, currency, alternative, cash, private equity, crypto, and unknown. Fund classification can contain more than one type. A name such as “Income” does not itself establish a fixed-income classification.

Two equity sleeves can contribute to the same total equity exposure. A mixed fund can contribute to both equity and fixed income even when it occupies one sleeve. This is why total equity exposure and the weight of a particular equity sleeve need not match.

A factor exposure band monitoring policy can use an asset-class type for its exposure check. It can therefore monitor total classified equity or fixed-income exposure rather than an individual sleeve. It can also use other supported exposure categories. Classification and coverage matter: unknown exposure should not be silently treated as a known asset class. See [factor exposure bands](/advisor/monitoring-explained#factor-exposure-measures-absolute-and-benchmark-relative-bounds) for policy behavior.

## Composites are shared

A composite belongs to your organization, and several models can hold it. In Global 80/20, US Large Cap sits inside US Equity; other models can hold US Large Cap at their top level or inside a different composite. A change to what a composite holds, or to the tilts and direct indexing it gives one of its sleeves, applies to every model that holds it and to every account on those models. Before you apply the change, Tilt lists the models it reaches and counts the accounts that set those sleeves differently from the model. [Build a model portfolio](/advisor/build-model-portfolio#3-create-or-change-a-shared-composite) shows where.

A model is also a shared sleeve. Changing its composition reaches accounts that hold it, whether as their primary model or as an additional sleeve. Account-owned portfolio weights stay in place while the shared definition changes within them.

## Archived sleeves stay in the models that hold them

Archive a sleeve to keep other models from adding it. Open Models, then Sleeves, select the sleeve, and choose Archive from its actions menu. A sleeve that a model holds can't be deleted, so Tilt offers Archive sleeve instead.

Models that already hold an archived sleeve keep it at its target, and their accounts keep holding and trading it. It shows Archived in a model's Allocation and in an account's Sleeves, and accounts can still set its tilts and direct indexing. The sleeve itself stays as it is, including what an archived composite holds, until you choose Unarchive. To stop holding it, remove it from each model.

## Accounts customize how sleeves are managed

An account's weights come from its primary model or its own portfolio composition. It can also change what a sleeve holds and how it's managed:

| Account setting | Where it applies |
| - | - |
| What the sleeve holds | Any sleeve. The account can hold another of your organization's sleeves, or, for a building block, its own ETF, index, Tilt, security, or basket. |
| Tilts | Any of the model's top-level sleeves, and any building block inside a composite |
| Direct indexing | Any building block that supports it, at any level |

Tilts on a top-level composite reach every sleeve it holds; [How a tilt changes a sleeve](#how-a-tilt-changes-a-sleeve) shows the arithmetic.

A customization of a sleeve inside a composite belongs to that place in the model's tree. Direct indexing set on one of the model's top-level sleeves reaches further: it also applies wherever the same sleeve appears inside a composite, unless the account customizes that place on its own. If a model holds US Large Growth both as a top-level sleeve and inside US Large Cap, turning on direct indexing for the top-level sleeve turns it on in both places. To keep the US Large Cap occurrence different, customize that row as well.

Customizations follow their sleeve when the model changes. Move a customized sleeve and the customization moves with it. Remove it and the customization stays saved, ready to apply again if the sleeve comes back. Tilt stops a change only when it can't tell where a customization belongs: when a customized sleeve leaves its place and now appears in more than one place.

[Tailor a client account](/advisor/tailor-account) covers customizing a sleeve. [Settings and rules](/advisor/configuration-and-rules) explains how account, model, and organization settings combine. [How optimization makes tradeoffs](/advisor/optimization-explained) explains why proposed holdings can still differ from the target.

## How a tilt changes a sleeve

A Tilt changes the target holdings of the sleeve where you apply it and every leaf sleeve beneath it. On a composite containing both direct-indexed and ETF sleeves, it can introduce individual ticker targets into both. To confine that change to one leaf sleeve, **apply the Tilt to that leaf sleeve**.

The weights below are targets. Proposed and actual holdings depend on optimization and the account's constraints.

A tilt's weight is a share of the building block it reaches. A +10% tilt scales the building block's base target weights down to 90% and fills the other 10% with the Tilt's tickers at the Tilt's own weights. A ticker in both the base basket and the Tilt receives both contributions.

### A tilt on a composite

A tilt on a composite applies inside each building block the composite holds, **at every level below it**. Each building block keeps its target share of the composite and assigns 10% of its target weight to the Tilt's tickers. The base target weights shrink proportionally:

| What the composite holds | With a +10% tilt on the composite |
| - | - |
| Two sleeves at 50% each | 45% and 45% in each sleeve's base targets, plus 5% of the Tilt's tickers inside each sleeve |
| Two sleeves at 70% and 30% | 63% and 27% in each sleeve's base targets, plus 7% and 3% of the Tilt's tickers inside them |

In both cases the Tilt's tickers make up 10% of the composite, and the composite's share of the model stays the same.

Take an Equities composite that holds US Large Cap at 70%, direct indexed, and a Small Cap basket at 30%, with Quality Leaders +10% set on Equities. US Large Cap targets its index's tickers at 63% of Equities and Quality Leaders' tickers at 7%. A ticker in the index and in Quality Leaders gets both amounts. The Small Cap basket targets each of its tickers at 90% of its basket weight, 27% of Equities in total, and Quality Leaders' tickers at 3%.

### What each kind of building block targets after a tilt

| Base implementation | Target with Quality Leaders +10% |
| - | - |
| An index with direct indexing | The index's tickers at 90% of their weights, plus Quality Leaders' tickers |
| An ETF | The ETF at 90%, plus Quality Leaders' tickers as separate positions |
| An index or another Tilt | Its tickers at 90% of their weights, plus Quality Leaders' tickers |
| A basket | Each basket ticker at 90% of its weight, plus Quality Leaders' tickers |
| A single security | The security at 90%, plus Quality Leaders' tickers at 10% |

Turning Direct indexing off keeps a benchmark ETF as the base holding; it **does not prevent a Tilt from adding individual ticker targets** alongside that ETF.

> [!NOTE]
>
> We could add an option to apply a Tilt only to tickers already in a sleeve's base benchmark. This option is **not currently supported**. If it would help your workflow, let us know through **Help & feedback** in the user menu.

To keep a Tilt's tickers in one building block, such as a direct-indexed sleeve, set the tilt on that building block. In a model, use **Tilts and direct indexing…** under In the composite on that sleeve's row. In an account, use **Customize** on the building block inside the composite.

### Compare parent and building-block placement

Consider an illustrative model with Equities at 50% of the model. Equities holds a direct-indexed US Large Cap building block at 70% and a Small Cap ETF building block at 30%, with direct indexing off for the ETF. Assume no existing tilts and a long-only Quality Leaders Tilt.

Compare setting Quality Leaders +10% on Equities with setting it only on US Large Cap. All percentages in this table are **of Equities**:

| Target contribution | +10% on Equities | +10% on US Large Cap only |
| - | - | - |
| US Large Cap's original index tickers | 63% | 63% |
| Quality Leaders through US Large Cap | 7% | 7% |
| Small Cap ETF | 27% | 30% |
| Quality Leaders through Small Cap | 3% | 0% |
| Total | 100% | 100% |

The parent placement funds the Tilt by reducing both base holdings: US Large Cap contributes 7 percentage points and Small Cap contributes 3. The building-block placement funds it only from US Large Cap, leaving the ETF target unchanged. The Tilt's contribution is therefore 10% of Equities in the first case and 7% in the second. Since Equities is 50% of the model, those contributions are 5% and 3.5% of the whole model. The same +10% setting expresses different total exposures depending on where you put it.

> [accordion] Worked example: a ticker in both the index and the Tilt
>
> Suppose a ticker is 2% of the large-cap index and 20% of Quality Leaders. Within US Large Cap, its adjusted target is `90% × 2% + 10% × 20% = 3.8%`.
>
> With parent placement, Small Cap contributes another `30% × 10% × 20% = 0.6%` of Equities to the same ticker. Add the contributions across leaves, then multiply by Equities' 50% share of the model:
>
> | Placement | Ticker target within Equities | Ticker target within the model |
> | - | - | - |
> | Equities parent | 70% × 3.8% + 0.6% = 3.26% | 1.63% |
> | US Large Cap only | 70% × 3.8% = 2.66% | 1.33% |
>
> The ticker is a separate position from the ETF. Any exposure to it inside the ETF is indirect and is not added to this individual ticker target.

To keep the added individual ticker targets out of the ETF building block, put the Tilt on US Large Cap only. This placement controls which targets change. It does not restrict optimization to trades in US Large Cap: the optimizer considers the account's holdings, taxes, costs, and constraints together, and can propose trades elsewhere. See [How optimization makes tradeoffs](/advisor/optimization-explained).

Tilts add up along a building block's path: the model's, a composite's, and the account's. Tilt refuses a change to an account, a model, or a composite that would raise the positive tilt adjustments on any account's sleeve above 100% in total.

### Preview without saving

In an account's **Setup**, select **Customize** on a top-level composite and edit its **Tilts**. **Weights with these tilts** updates before you queue or apply the change. It shows combined holding weights within the selected composite, then each building block's target share of that composite and holding weights within that building block. **Before** is the base basket before the adjustments; **After** includes the adjustments in the preview. It is not a comparison with current account holdings or a proposed trade list.

The preview uses saved descendant settings, including account customizations. It does not include unrelated edits waiting in the change queue, and it is unavailable while you change what that place holds. Inspect the percentages at their displayed level; multiply by the composite's model share to express the combined weights as whole-model targets. Select **Cancel** to leave without queueing the edits. No optimization is needed to inspect these target weights.

This composite preview does not provide a side-by-side comparison with a proposed Tilt on one nested building block. Review the full allocation and effective settings when comparing those placements; a calculation for a building block alone does not establish the whole account's targets. The optimizer trades toward the saved targets within the account's constraints, so a proposal can hold different amounts.

## Configurations group accounts that match

A configuration is a set of accounts on one model that customize its sleeves in exactly the same way. Tilt compares what each account holds, its tilts, and its direct indexing on every sleeve in the model's tree with the model's own values.

Weights must match exactly: accounts with Quality Leaders +10% and accounts with Quality Leaders +5% on the same sleeve form two configurations. A setting that repeats the model's value changes nothing, and neither does a customization of a sleeve the model no longer holds. Tax settings, restrictions, and other account settings don't affect an account's configuration.

Accounts with no differences are As modeled. A model whose accounts form many configurations may hide variants that deserve a model of their own. [Compare a model's account configurations](/advisor/compare-account-configurations) shows where to read them.

***

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.


# How monitoring policies work
Source: https://docs.tilt.now/advisor/monitoring-explained

Understand model drift, ex ante tracking error, cash bands, factor exposure, and the monitoring results they produce.

Monitoring policies help you identify client accounts and households that need review. **Model drift** checks allocation alignment, **sleeve tracking error** estimates benchmark-relative return variability, **cash bands** check cash levels, and **factor exposure** checks asset allocations or risk exposures against bounds. Each check measures a different part of the portfolio.

A policy sets the scope, conditions, and limits for a check. Tilt applies those limits to a dated observation and records the result. A warning or breach points you toward a review, raising cash, or deploying cash. You make the subsequent proposal and trade decisions.

Manage policies in **Firm → Setup → Monitoring**. Edit firm values in the dialog, then review the queue and select **Apply firm changes**. Each watch also links to its model and account overrides. [Manage monitoring policies](/advisor/monitoring-policies) walks through the manual editor and inspection with Tilt Agent.

| Check | Question it answers | Measurement |
| - | - | - |
| Model allocation drift | Have the amounts allocated to the models moved away from their targets? | Absolute weight differences, in percentage points. |
| Ex ante sleeve tracking error | How much return variability relative to the benchmark is estimated for the current sleeve? | Annualized standard deviation of active returns, shown as a percentage. |
| Cash band | Is the account's cash inside its permitted range? | Cash in USD or as a percentage of account value. |
| Factor exposure | Are asset allocations or risk exposures inside their permitted ranges? | Absolute exposure and exposure relative to a benchmark, in the selected factor's units. |

A **model portfolio** defines target allocations. A **sleeve** is a component of that portfolio, such as its US equity allocation. A **benchmark** defines the reference constituent weights for a sleeve. A constituent's **active weight** is its current weight within the sleeve minus its benchmark weight.

## Model allocation drift measures changes in allocation

Tilt attributes current eligible holdings to the top-level model allocations, then compares each allocation's current share with its target share. If a ticker belongs to more than one sleeve, Tilt uses its benchmark contributions to distribute the holding across sleeves. A Tilt's tickers count toward the Tilt's own row under the sleeve it is set on, as [Where a Tilt's tickers count](/advisor/models-and-benchmarks#where-a-tilts-tickers-count) explains. Sleeves below the top level show their target and current weights with no drift limit.

The current weights use eligible invested holdings and any excess cash as their denominator. Tilt excludes manually held assets, the legacy non-tradable balance, and the account's cash reserve from the model drift basis. The cash reserve is the cash an account keeps on purpose: Tilt takes the larger of the account's cash buffer and the model's cash target in US dollars and in Canadian dollars, and adds the two. Cash above the reserve is **excess cash**. It stays in the current denominator with a target of zero, like an off-model holding. Tilt normalizes target allocations over their investable share. Check the reported drift basis and excluded values when comparing drift with total account value.

Eligible holdings that Tilt cannot attribute to a model appear as **off-model** exposure. They remain in the current denominator and have a target of zero, so unmatched holdings contribute to total drift.

### See where a holding counts

On an account's **Holdings** tab, select a holding's **Weight** to see where it counts in the account's model. Each line names a sleeve by its path, such as **Global Equity > US Core**, with the share of the account that counts there. A ticker that two sleeves hold shows one line for each sleeve, and the lines add up to the holding's weight.

![Holdings table with VTI's weight of 36.55% selected. A popover reads VTI counts toward, 36.55% of account, with Global Equity > US Core at 22.55% and Global Equity > US Tax-Managed at 14.00%, and At Oct 27, 2026 prices.](https://mintcdn.com/tilt/d7hh-6Oiu59ZcYdg/images/advisor/northwind-holding-counts-toward.jpg?fit=max\&auto=format\&n=d7hh-6Oiu59ZcYdg\&q=85\&s=2a73f62a728c4fe8bc3faea0ebf808f1)

Some lines end in a label:

| Label | Meaning |
| - | - |
| **Tilt** | The holding counts in a Tilt's own row under the sleeve the Tilt is set on. |
| **Legacy** | The holding is an accepted [legacy holding](/advisor/transition-legacy-holdings) and counts in the sleeve you assigned it to. |
| **Off model** with **Not in any sleeve** | No sleeve or Tilt in the model holds the ticker, so it adds to off-model exposure. |

![Holdings popover for ARKK at 2.73% of account showing Off model with a Not in any sleeve label, the note Tilt sells these over time, within this account's tax settings, and At Oct 27, 2026 prices.](https://mintcdn.com/tilt/d7hh-6Oiu59ZcYdg/images/advisor/northwind-holding-off-model.jpg?fit=max\&auto=format\&n=d7hh-6Oiu59ZcYdg\&q=85\&s=1be0cee220edcb5d9820c587e0851a8e)

Tilt values the holdings at the latest prices, so you can check an account before its first optimization or drift check. A client's or household's **Holdings**, and an account without a model, show plain weights. Tilt Agent answers the same question for an account, such as "What sleeve is VTI in?".

After a ticker leaves a benchmark, you may still hold it in a directly indexed sleeve. When dated benchmark records show where it belongs as of the evaluation, Tilt keeps it in that sleeve. The holding counts toward the sleeve's current weight, while its target weight within the sleeve stays at zero.

When an account has excess cash, it also gets its own breach check. Tilt compares the excess cash weight with the individual allocation limit and suggests deploying cash when it is strictly above that limit. This check differs from a cash band. A cash band compares an account's total cash with a permitted range; the excess cash check compares only the cash above the reserve with the allocation limit. The cash buffer and the cash band are separate settings, so either check can breach without the other.

### Total drift avoids counting the same shift twice

Consider this illustrative portfolio:

| Allocation | Target weight | Current weight | Absolute difference |
| - | - | - | - |
| US equity | 60% | 67% | 7 percentage points |
| Fixed income | 40% | 33% | 7 percentage points |
| Off-model | 0% | 0% | 0 percentage points |

Total drift is half the sum of the absolute model allocation differences, the off-model weight, and the excess cash weight. In this example, half of 7 plus 7 is **7% total drift**. Dividing by two avoids counting the same shift into one allocation and out of another twice.

The individual allocation check measures the absolute difference for each model. With an illustrative total breach limit of 6% and an individual allocation limit of 5 percentage points, this portfolio breaches both checks.

If the same targets instead have current weights of 54% US equity, 36% fixed income, and 10% off-model, total drift is half of 6 plus 4 plus 10, or **10%**. Tilt reports the off-model holdings in the drift detail; it does not create a separate off-model breach check.

Excess cash counts the same way. Consider a \$500,000 account with a \$10,000 cash reserve that holds \$40,000 in cash and \$460,000 in holdings split 60% US equity and 40% fixed income. Its drift basis is \$490,000: the holdings plus \$30,000 of excess cash. US equity is 56.33% of that basis, 3.67 percentage points below target. Fixed income is 37.55%, 2.45 percentage points below target. Excess cash is 6.12%, against a target of zero. Total drift is half of 3.67 plus 2.45 plus 6.12, or **6.12%**. With the illustrative limits above, total drift breaches its 6% limit, and the excess cash check breaches its 5 percentage point limit and suggests deploying cash.

### Allocation differences use percentage points

A target of 60% and a current weight of 67% differ by **7 percentage points**. Tilt uses that absolute weight difference. A relative calculation of 7 divided by 60 measures a different quantity.

## Ex ante tracking error measures estimated return variability

Tilt evaluates tracking error for positive-weight sleeves against their resolved benchmarks, whether or not direct indexing is enabled. It compares current attributed constituent weights, normalized within each sleeve, with the sleeve's benchmark weights. The monitoring observation uses the current holdings.

Tilt combines the active weights with estimated variances and covariances. Covariance describes how constituent returns move together. The square root of the resulting active-return variance gives tracking error, expressed on an annualized basis.

The factor-model estimator combines common factor exposures, factor covariance, and constituent-specific risk. A policy can also select a historical covariance estimator, which uses aligned daily USD total returns to estimate those relationships. If factor-model coverage is unavailable or incomplete, Tilt tries historical covariance for that sleeve when its benchmark and attribution allow evaluation. This fallback also applies to transition and destination tracking error for legacy holdings.

The same policy limits apply after that estimator switch. Different estimators can produce different values for the same holdings, so inspect the reported estimator, fallback reason, and coverage when comparing results across dates.

Historical covariance still evaluates the current fixed active weights. It is an **ex ante** estimate informed by history. **Ex post** tracking error measures the variability of the portfolio's actual realized return differences over a historical period.

### The resolved benchmark defines the comparison

Tracking error helps you assess how closely a sleeve follows its intended reference portfolio. Check that its resolved benchmark and policy limits match the sleeve's mandate, including intentional customization. An intentionally active sleeve can have higher tracking error while remaining aligned with its investment objective.

Tilt treats ETFs in a configured alternative set as equivalent for this check. It combines their current weights and benchmark weights into a representative ETF before calculating tracking error. Differences between those approved alternatives therefore do not contribute to the measured tracking error. Read the result as a comparison against the resolved implementation benchmark.

### Compare monitoring with a proposal

Monitoring measures your current holdings. A proposal measures the holdings you would have after its trades. With the same holdings, benchmark, date, and measurement settings, the results should agree. A change in holdings can produce a different tracking error.

If you keep legacy holdings during a transition, monitoring can compare them with the accepted transition plan, while a proposal compares against the destination benchmark. Check which reference each result uses before expecting the values to match.

### The same weight differences can produce different risk

Consider a sleeve with these illustrative weights:

| Constituent | Benchmark weight | Current sleeve weight | Active weight |
| - | - | - | - |
| Ticker A | 50% | 60% | +10 percentage points |
| Ticker B | 50% | 40% | −10 percentage points |

Assume each ticker has annualized volatility of 20% and their return correlation is 0.80. These active weights produce tracking error of approximately **1.26%**. With illustrative warning and breach limits of 1% and 2%, the sleeve triggers a warning and passes the breach check.

With the same weights and volatilities but zero correlation, tracking error rises to approximately **2.83%** and breaches the 2% limit. The risk relationships determine how weight differences translate into return variability.

### Interpret tracking error at the sleeve level

Tracking error of 2% describes estimated annualized variability of returns relative to the benchmark. It gives you a measure of dispersion, rather than a forecast of underperformance or a maximum return gap. Future realized tracking error can differ from the estimate. The estimate can change when the risk model or return history changes, even if holdings stay constant.

A warning or breach prompts you to review the cause. Compare holdings, benchmark changes, and estimator changes before deciding whether a rebalance is appropriate. A higher estimate can reflect changed market risk for the same holdings.

The metric uses weights normalized within the sleeve. It does not measure that sleeve's contribution to total account tracking error. Calculating an account total would also require the risk relationships between sleeves.

### Legacy holdings have transition and destination references

Suppose an account still owns an older ETF assigned to US Large Cap, but the final portfolio will hold other investments. Tilt monitors both stages:

| Measure | What Tilt compares current holdings with |
| - | - |
| **Transition tracking error** | The saved plan, including the accepted quantity of the older ETF and replacement investments for the rest of the sleeve. Tilt values that quantity at current prices. |
| **Destination tracking error** | The final portfolio, where the older ETF has zero weight. |

Tilt includes the legacy holding's current value in its assigned sleeve for allocation drift and tracking error. The transition reference embeds the accepted retained quantity at current prices and allocates the rest to replacement holdings. A low transition tracking error can therefore mean the sleeve follows its plan while destination tracking error remains higher. The legacy non-tradable balance remains excluded from model drift.

Optimization uses the destination benchmark, with zero weight in the legacy holding, to sell it down within the account's constraints. A legacy sell-down opportunity prompts advisor review when the final sale meets the configured threshold and fits the applicable tax constraints, including remaining annual gains capacity when a budget applies. Other monitoring rules can still prompt review for their own reasons.

Find both measures and their dates under **Setup → Settings → Legacy holdings → Tracking error details**. An unavailable result is not zero risk. If the assignment shows **Needs review**, review and save it again. [Transition legacy holdings into a sleeve](/advisor/transition-legacy-holdings) shows the steps.

For a valid legacy transition, monitoring applies the tracking-error policy limits to **transition tracking error**. Both legacy comparisons require factor-model coverage. Destination tracking error remains visible, even when the transition check passes. The **Sell-down alert threshold** instead measures the size of a proposed sale. [The legacy-holdings guide](/advisor/transition-legacy-holdings#2-understand-how-legacy-holdings-contribute-to-tracking-error) gives the formulas and a worked example.

## Drift and tracking error can signal different issues

A portfolio can keep its target allocation between models while holding different constituents inside a sleeve. Its allocation drift can be low while tracking error is high. Conversely, model allocations can move away from target while each sleeve continues to replicate its benchmark closely.

Use drift to examine allocation alignment. Use tracking error to examine the return variability associated with constituent differences inside a sleeve. The example limits on this page illustrate the calculations; inspect the policies that apply to your account for its actual limits.

## Cash bands measure cash against a permitted range

A cash-band policy sets a lower and upper cash limit. It can express those limits as USD amounts or as fractions of account value. For a percentage band, Tilt divides the observed cash balance by account value. The dollar check uses the cash balance valued in USD.

For an illustrative account worth \$100,000 with a 2% to 5% cash band:

| Cash balance | Cash as a percentage of account value | Result |
| - | - | - |
| \$1,000 | 1% | Lower bound breaches; the suggested action is to raise cash. |
| \$2,000 | 2% | At the lower bound; both checks pass. |
| \$4,000 | 4% | Inside the band; both checks pass. |
| \$5,000 | 5% | At the upper bound; both checks pass. |
| \$6,000 | 6% | Upper bound breaches; the suggested action is to deploy cash. |

A dollar band keeps the same dollar limits as account value changes. A percentage band changes the corresponding dollar range with account value. Cash bands produce breach checks for each boundary, without a separate warning level. A missing or invalid cash observation makes the check unevaluated; a percentage check also needs a positive account value.

## Factor exposure measures absolute and benchmark-relative bounds

A factor-exposure policy checks each selected exposure against an absolute range and an active range. **Absolute exposure** is the measured exposure itself. **Active exposure** is absolute exposure minus the selected benchmark's exposure. Each range has a minimum and maximum, and Tilt records a result for each boundary.

### Asset-class types can define exposure bands

**You can use an asset-class type as the factor in a factor-exposure band.** Select a type such as equity, fixed income, or cash to monitor the combined exposure to that type across the holdings. For example, an equity band of 50% to 70% checks the portfolio's total equity exposure; an active equity band of −3 to +3 percentage points checks its difference from the benchmark's equity exposure.

Asset-class bands are available for account, model portfolio, and organization policies. The policy scope determines whether Tilt measures the account or the household, as described below. The worked equity example on this page illustrates both absolute and active asset-class bands.

### Scope determines the portfolio being measured

| Policy scope | Evaluation level | Supported exposure checks |
| - | - | - |
| Account or model portfolio | Each applicable client account. | Asset-class exposures, such as equity, fixed income, and cash, including unknown exposure. |
| Organization | Household. | Asset-class exposures and factors from the selected risk model. |

An account or portfolio policy measures the account's asset-class exposures from its holdings. This differs from model drift: drift measures allocation to the assigned models, while asset-class exposure measures the holdings' classifications. Two models can both contribute equity exposure.

For organization policies, Tilt combines the household's account positions in proportion to their account values. An account worth USD 300,000 has three times the weight of an account worth USD 100,000. Household checks require complete member-account evaluation and position snapshots; an incomplete household cannot establish an in-range result.

Risk-factor values use the selected model's loading scale. Read those values in their factor units. Asset-class exposures are fractions that can be read as percentages; a risk-factor loading does not necessarily represent a percentage allocation.

### Absolute and active limits can give different results

Suppose an account has 65% equity exposure and its policy benchmark has 60%. Its active equity exposure is **+5 percentage points**.

| Check | Illustrative permitted range | Measured value | Result |
| - | - | - | - |
| Absolute equity exposure | 50% to 70% | 65% | Both absolute checks pass. |
| Active equity exposure | −3 to +3 percentage points | +5 percentage points | Active maximum breaches. |

At exactly 70% absolute exposure or +3 percentage points active exposure, the corresponding maximum check passes. Values strictly outside a range breach. Factor-exposure checks have no separate warning level and suggest reviewing a rebalance when they breach.

Coverage applies to each measurement. Missing factors, insufficient classification or factor coverage, and unavailable benchmarks can leave checks unevaluated. An absolute check can still be evaluable when the benchmark needed for its active check is unavailable. Unknown asset-class exposure records holdings without a classification; inspect it alongside the coverage detail.

## Applicable policies determine the limits

Policies can belong to the organization, a model portfolio, or a client account. Their entries can depend on a date or condition. Tilt evaluates applicable enabled entries, so more than one policy can produce results for the same metric. Drift, tracking error, and cash bands apply across those scopes to account checks. Factor-exposure policies use the account or household evaluation levels described above.

For example, an applicable organization policy with a 2% tracking error breach limit and an account policy with a 3% limit can both evaluate a sleeve. A measurement of 2.5% breaches the organization check and passes the account check. The account still has a breach to review.

Disabling an account or portfolio policy leaves any applicable broader policies available for evaluation. Inspect each result's source, enabled state, conditions, and evaluation date to understand which checks apply. [Manage monitoring policies](/advisor/monitoring-policies) explains how to inspect and change a policy.

### Warnings include the limit and breaches exceed it

| Check | Triggers when | At exactly the limit |
| - | - | - |
| Total drift warning | Measured drift is at or above the warning limit. | Warning. |
| Total drift breach | Measured drift is strictly above the breach limit. | Breach check passes. |
| Individual allocation breach | Absolute allocation difference is strictly above the limit. | Breach check passes. |
| Excess cash breach | Excess cash weight is strictly above the individual allocation limit. | Breach check passes. |
| Sleeve tracking error warning | Measured tracking error is at or above the warning limit. | Warning. |
| Sleeve tracking error breach | Measured tracking error is strictly above the breach limit. | Breach check passes. |
| Cash or factor minimum | Measured value is strictly below the minimum. | Minimum check passes. |
| Cash or factor maximum | Measured value is strictly above the maximum. | Maximum check passes. |

At exactly 6% total drift, a 6% breach check passes. A separate 3% warning check still triggers. Above the breach limit, both rows can trigger; the account is classified as breached.

## Read results together with coverage

A monitoring report is a dated snapshot. Check the evaluation date, holdings freshness, and price freshness before relying on its values. The [daily briefing](/advisor/daily-briefing) brings the report's account status, coverage, and possible next steps into one review.

| Account status | Meaning |
| - | - |
| Breached | At least one evaluated check breached. Other checks may still be unavailable. |
| Drifting | A warning triggered, with no breach and no unevaluated check in the classification. |
| Holding | The evaluated checks produced no warning or breach. Confirm which checks were applicable. |
| Skipped | Tilt could not establish a complete result. Inspect the stated reason. |

Tilt assigns the account status in order: **Breached** if any evaluated check breached; otherwise **Skipped** if any check was not evaluated; otherwise **Drifting** if any check warned; otherwise **Holding**. An account with no breach, a warning, and an unevaluated check is therefore Skipped, and the warning remains in its check results.

Tilt marks a rule **not evaluated** when it cannot calculate a reliable observation. Reasons include missing benchmark weights, incomplete model attribution, unavailable return history, unsupported benchmarks, or invalid inputs. If factor-model coverage is insufficient and historical covariance also cannot produce a result, tracking error remains unevaluated.

Household factor results have their own classification. A household is **breached** if any evaluated factor bound breaches, **skipped** if there is no breach but a required check is unavailable, and **holding** when its evaluated checks pass. Confirm which policies applied before interpreting a holding result.

A missing value does not establish that the account is within its limits. Investigate the reason and check report coverage before drawing a conclusion.

## A monitoring signal leads to a review

Inspect the account or household, date, measured value, threshold, comparison operator, and policy source. Then examine the affected allocations, sleeve constituents, cash balance, or factor exposures and their coverage details. Consider why the deviation exists, including intentional customization, restrictions, cash needs, and tax considerations.

Account and portfolio asset-class policies can also contribute bounds to proposal construction when classification coverage is sufficient. Monitoring still evaluates all applicable policies, while construction uses the effective account or portfolio policy. Inspect the reported construction-constraint status to see whether those bounds were applied to a proposal.

The monitoring calculation can save optimization proposals for review. Saving a policy or producing a report does not submit orders. [Review a rebalance](/advisor/review-rebalance) explains the separate proposal and trade decisions.

***

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.


# Manage monitoring policies
Source: https://docs.tilt.now/advisor/monitoring-policies

Edit firm monitoring values and model or account overrides in Firm Setup, then review and apply queued changes.

Monitoring policies help an advisor watch model drift, sleeve tracking error, cash bands, and factor exposure. A policy can belong to the organization, a model portfolio, or a client account. Select the exact scope and rule type before changing it.

[How monitoring policies work](/advisor/monitoring-explained) explains drift, tracking error, cash bands, factor exposure, threshold boundaries, and evaluation results.

## 1. Open Monitoring in Firm Setup

Open **Firm** in the left sidebar, then **Setup**. Under **Defaults for models and accounts**, select **Monitoring**. The dialog shows the firm's four watches:

| Watch | Values in the editor |
| - | - |
| **Model drift watch** | **Warn at (optional)**, **Breach at**, and **Allocation breach at**. |
| **Sleeve tracking watch** | Tracking error limits: **Warn at (optional)** and **Breach at**. |
| **Cash band watch** | **Low** and **High**, with **Measured in** set to **Percent of value** or **Dollars**. |
| **Factor exposure watch** | Factor bounds: **Min**, **Max**, **Active min**, and **Active max**. |

Monitoring policy management lives in **Firm → Setup**. Use **Automations** for scheduled assignments and their signals.

## 2. Edit firm values

Select a watch in the **Monitoring** dialog to edit its firm limits in the focused editor. The watch list shows each watch's status and, on wider screens, its current values. Switching watches keeps your queued edits. If the firm has no policy of a type, select **Set firm values** to start one.

Select **Done** to return to Setup. Your edits stay in **Queued changes**, alongside other firm setting changes. Open the queue, review each watch and its values, then select **Apply firm changes** to save. Changing a field or selecting **Done** alone does not save the policy.

For a model or account override, select **Manage overrides** under that watch. The **Overrides** tab lists the models and accounts with their own policies. Search by name and select a row to edit it, or select **Add override** to create one. Check the account and client names before editing. Edits on this page have their own **Queued changes** and **Apply** action.

Policies with conditions or schedules display those entries as text in the manual editor. Use Tilt Agent when you need to change those entries.

## 3. Inspect the effective policy with Tilt Agent

Ask Tilt Agent: **"Show the cash-band monitoring policy for Taylor Morgan's account, including any portfolio or organization policy it inherits. Do not change it."**

Read the scope of each returned policy. In this demo, Taylor's account has no explicit override for these policy types, so the organization policies apply.

![Tilt Agent's monitoring readback states that organization policies apply to Taylor Morgan's account without account or portfolio overrides, then lists model drift and cash-band thresholds.](https://mintcdn.com/tilt/oX8YEO6TEUZnCHsR/images/advisor/runtime-monitoring-policies.jpg?fit=max\&auto=format\&n=oX8YEO6TEUZnCHsR\&q=85\&s=9c993d18b6374548f332637e56b82294)

Tilt Agent shows the applicable monitoring policies and their organization scope for Taylor's account.

Review whether the selected scope has its own policy, inherits a broader one, or has a disabled policy. Disabling an account or portfolio policy can restore a broader enabled policy; it does not necessarily stop monitoring. Check the effective result before deciding what to change.

## Propose a dated change in chat

Ask: **"Propose the cash-band limits I specify for this account, simulate them on the dates I choose, and show the complete replacement before saving."** Review the selected account, rule type, ordered entries, dates, and inherited behavior. A proposal or simulation does not save the policy.

Confirm the complete change, then ask Tilt Agent to read back the saved policy. If another change occurred, inspect and propose again rather than retrying an outdated confirmation. Factor-exposure policies use their own scope-specific inspection; name the organization, portfolio, or account you mean.

[Dynamic Rules](/advisor/configuration-and-rules) resolve optimization settings for an account. Monitoring policies provide oversight and alert conditions; saving one does not submit an optimization or place an order.


# Onboard a client
Source: https://docs.tilt.now/advisor/onboard-client

Create a new advisor client and account, select a model, add holdings, and check readiness.

Use onboarding when a new client needs a managed account in your advisor organization. This example follows the proposed setup for synthetic client **Alex Rivera**. Have an authoritative client reference, account holdings, and a model portfolio available before you expect the account to be ready for optimization.

## 1. Start the new-client workflow

Ask Tilt Agent: **"Help me onboard a new client named Alex Rivera in my advisor organization. Show each proposed change before saving it."**

Tilt Agent opens the client onboarding workflow. Expand its progress card to see the current step and the remaining setup steps. The example below has not created a client.

![Expanded Client onboarding workflow card shows zero of six steps complete and Create client as the current step.](https://mintcdn.com/tilt/oX8YEO6TEUZnCHsR/images/advisor/runtime-onboarding-workflow.jpg?fit=max\&auto=format\&n=oX8YEO6TEUZnCHsR\&q=85\&s=ab002087844b960ed63f276105b05849)

Tilt Agent's onboarding card shows Create client as the current step, followed by account source, suitability, portfolio, starting position, and readiness steps.

Ask Tilt Agent to propose the client identity and check for a possible duplicate before creation. Review the proposed identity and confirm the creation. A new client comes with a default account; check that account in the saved result before adding source details. If the identity already exists, resolve the match rather than creating another client.

The workflow card shows the current step and the next action. A blocked step calls for missing information or a decision; it does not mean later steps were completed.

## 2. Record account context

Provide the account type and a non-sensitive provider label if you have them. In this workflow, these details form an internal account-source placeholder. They do not connect a custodian or import holdings. Do not enter credentials or connection secrets in chat.

Tilt Agent then collects a suitability brief: objective, time horizon, risk tolerance, liquidity needs, jurisdiction and tax context, and restrictions. Review the complete brief and correct it before selecting a model. The brief is workflow context, not an approved or signed investment policy statement.

## 3. Select a model and tailor the account

Ask: **"Compare the available model portfolios with Alex Rivera's confirmed brief, then show the model and account changes you propose."** Review the model's sleeves and target weights. Confirm model assignment separately from model creation or account-specific changes. A reusable model should remain shared; client restrictions and preferences belong on the account.

Read [Tailor an account](/advisor/tailor-account) for the settings and confirmation flow. If no suitable model or required sleeve exists, finish that setup before claiming the account is ready.

## 4. Add holdings and check readiness

Supply authoritative starting cash and holdings data for the exact account. Review the proposed replacement before confirming it, then ask Tilt Agent to show the saved holdings. A provider label is not evidence that positions were imported or refreshed.

Ask: **"Check Alex Rivera's account readiness and list anything still missing."** Check the saved model, account settings, holdings, and reported blockers. When the account is ready, [review a rebalance](/advisor/review-rebalance). Onboarding alone does not run an optimization or place an order.


# Configure optimization for the proposal you need
Source: https://docs.tilt.now/advisor/optimization-configuration

Diagnose unwanted sales, missed harvesting opportunities, and conflicting settings before changing an account configuration.

Start with the outcome you want for the account: harvest losses, reduce a concentrated position, or raise cash. Then check whether the account's settings require trades that conflict with that outcome.

For example, a loss-harvesting proposal can sell appreciated holdings because an exposure limit requires it. Raising **Tax sensitivity** will not remove that requirement. Identify what is driving the sale before changing how much weight the optimizer gives taxes.

The examples below use simplified portfolios to show how a setting can change the proposal and what you give up in return. Dollar figures are rounded.

## Leave room for tax-loss harvesting

A tight factor bound can require selling appreciated holdings even when your priority is harvesting losses.

Consider a simplified \$1 million portfolio. With the same holdings and tax settings, both configurations harvest \$80,000 of losses:

| | Tighter factor bound | Wider factor bound |
| - | - | - |
| Losses harvested | \$80,000 | \$80,000 |
| Gains realized | \$35,000 | \$0 |
| Net realized loss | \$45,000 | \$80,000 |
| Factor exposure relative to the benchmark | Smaller deviation | Larger deviation |

Selling the loss position changes the portfolio's factor exposure. Under the tighter bound, the optimizer also sells part of an appreciated holding to bring exposure within range. The wider bound lets it keep that holding, accepting more exposure deviation in return.

The choice is whether closer exposure matching justifies the additional gains. Where the mandate allows flexibility, compare a wider bound before increasing **Tax sensitivity**: a stronger tax preference cannot override a required exposure limit.

Open **Setup → Settings → Constraints** to review **Factor exposure bounds**, including inherited values. Position caps and **No-hold tickers** can also require gain-realizing sales, so check those alongside factor bounds.

[Set factor exposure bounds](/advisor/set-factor-exposure-bounds) walks through the app's fields, allocation-factor units, and saving a change at account, model, or firm scope.

## A loss position stays in the portfolio

A no-trade restriction preserves a position, including when selling it could harvest a loss.

Return to the \$1 million portfolio above with the wider factor bound. One holding is worth \$400,000 against a cost basis of \$480,000. Compare keeping its no-trade restriction with allowing it to trade:

| | No-trade restriction | Trading allowed |
| - | - | - |
| Original holding retained | \$400,000 | \$0 |
| Replacement purchased | \$0 | \$400,000 |
| Losses harvested | \$0 | \$80,000 |

Keeping the restriction preserves the original holding. Allowing the trade makes the loss available, but replaces that investment and changes the portfolio's exposure. Remove an optional restriction only when its reason no longer applies; an unrealized loss alone does not make it appropriate to sell.

Check **No-trade tickers**, including restrictions inherited from the model and firm. If both no-hold and no-trade apply, no-trade takes precedence. Wash-sale restrictions and replacement eligibility still matter after a no-trade restriction is removed. [Tax-aware management](/advisor/tax-aware-management) explains those checks and the limits of the tax estimate.

## A transition needs more turnover than the limit allows

A lower **Turnover limit** can spread a transition across proposals, leaving more of the original position in place.

Consider a \$1 million account with a \$100,000 holding you want to reduce to \$50,000 and reinvest in a replacement. The holding has a \$90,000 cost basis; the rest of the account stays unchanged.

| | 5% turnover limit | 10% turnover limit |
| - | - | - |
| Original holding sold | \$25,000 | \$50,000 |
| Replacement purchased | \$25,000 | \$50,000 |
| Original holding remaining | \$75,000 | \$50,000 |
| Gains realized | \$2,500 | \$5,000 |

The limit counts purchases and sales, excluding the cash residual. Selling \$25,000 and buying \$25,000 uses the full 5% allowance. The lower limit realizes fewer gains now but leaves the transition incomplete; the higher limit allows the account to reach its target in this example.

Decide whether the account can move in stages. If another constraint requires the whole change now, the smaller allowance may leave no feasible solution. [How optimization makes tradeoffs](/advisor/optimization-explained) explains the turnover measure and trading costs.

## A cash setting causes more sales than expected

A larger cash reserve provides more available cash, but can require more sales to fund it.

Consider a \$1 million account with \$5,000 already in USD cash. You set a **USD cash amount** of \$10,000. Compare that amount on its own with keeping a 2% **USD cash buffer** as well:

| | \$10,000 amount only | 2% buffer plus \$10,000 amount |
| - | - | - |
| Cash reserve | \$10,000 | \$20,000 |
| Additional cash to raise | \$5,000 | \$15,000 |

Tilt uses the larger reserve implied by the percentage and the amount. Keeping the 2% buffer reserves another \$10,000, which requires another \$10,000 of net sales if there are no other cash flows, before fees. Those sales may realize gains depending on which lots are sold.

Check both fields under **Setup → Settings → Optimization**. If the reserve is larger than intended, correct it before increasing tax sensitivity to discourage sales. If the cash is required, review the gains and exposure changes as part of funding it.

## Compare the whole proposal before choosing settings

Use an account-specific comparison before changing a shared model or firm setting:

1. Record the current effective settings and proposal results. Check each setting's source and any matching rules in **Setup**.
2. Change one relevant setting, apply it, and generate a new proposal from **Optimization → Optimize**. Keep the other inputs consistent so you can assess its effect.
3. Compare the resulting trades and holdings, including estimated gains and losses, cash, turnover, and exposure deviation. Choose the configuration against the account's mandate, rather than a single favorable metric.

In the factor-bound example, looking only at losses harvested shows a tie at \$80,000. Including gains reveals net realized losses of \$45,000 versus \$80,000, while the exposure comparison shows what the wider bound gives up. Read those outcomes together before choosing the configuration.

[Review a rebalance](/advisor/review-rebalance) covers proposal review. [Settings and rules](/advisor/configuration-and-rules) explains inherited values and conditional settings. [Reports and backtests](/advisor/reports-and-backtests) explains the available estimates and their limits.

***

Wash-sale rules may disallow a loss if substantially identical securities are bought within 30 days before or after the sale, including in the client’s other accounts, such as IRAs or a spouse’s accounts. The Platform’s wash-sale checks cover only accounts on the Platform, so confirm the client’s full position with a qualified tax professional.

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.

See [IRS Publication 550](https://www.irs.gov/publications/p550) for U.S. wash-sale rules.


# How optimization makes tradeoffs
Source: https://docs.tilt.now/advisor/optimization-explained

Understand how targets, risk, taxes, costs, and constraints shape a proposed portfolio.

Optimization turns an account's saved holdings, effective model allocation, and settings into a proposed portfolio and trades. A proposal can differ from the model because reaching the target also involves taxes, transaction costs, and account restrictions.

This page explains how to interpret those tradeoffs. [Review a rebalance](/advisor/review-rebalance) covers running and reviewing a proposal.

## Targets, preferences, and limits

Three kinds of input play different roles:

| Input | Role | Example |
| - | - | - |
| Target allocation | Describes the portfolio the account is trying to implement. | Sleeve weights and the holdings used to implement each sleeve. |
| Preference | Changes which feasible portfolio the optimizer favors. | More emphasis on tax benefits or a larger penalty for trading. |
| Constraint | Limits the portfolios or trades considered in a solve. | A position bound, turnover limit, cash requirement, or buy restriction. |

A preference is a tradeoff, rather than a promise about the final metric. Increasing tax emphasis can change the proposal, but does not by itself guarantee a specified tax bill. Similarly, a cost penalty does not mean estimated transaction costs must remain below that value.

Effective settings can come from the organization, model portfolio, account, and applicable Dynamic Rules. Read [settings and rules](/advisor/configuration-and-rules) to understand which values apply to the account.

Factor exposure bounds constrain the weighted exposure to built-in asset-allocation factors or custom asset loadings. Absolute bounds limit portfolio exposure; active bounds limit its difference from the optimization benchmark. [Set factor exposure bounds](/advisor/set-factor-exposure-bounds) covers the app's **Constraints** editor. The [optimizer factor reference](/customization/factor-bounds) lists supported names and units. Custom-factor upload is in development; the [API guide](/customization/configure-factor-bounds) documents the format and how to request setup. Check compatibility before using a factor from a monitoring catalog in optimization.

## What closeness to the target means

Tilt supports different ways of penalizing departures from the ideal portfolio. In the mean-variance configuration, the optimizer uses modeled factor and asset-specific risk to assess weight differences. In the weight-distance configuration, it penalizes squared differences in portfolio weights. The chosen configuration affects which departures are expensive to the optimizer.

Two proposals with the same total weight difference can therefore receive different risk penalties. Correlated holdings may partly offset each other in a risk model, while a concentrated exposure can contribute more risk.

The optimizer's distance from its ideal weights and a report's tracking error against a benchmark are related measures, but their reference portfolios and definitions need to be checked. [Models and benchmarks](/advisor/models-and-benchmarks) explains the references; [monitoring explained](/advisor/monitoring-explained) explains ex ante tracking error and drift.

## Why exact replication may be undesirable

Consider a hypothetical account with an overweight position that has a large unrealized gain. The following are possible choices, not outputs from an actual optimization:

| Choice | Potential advantage | Tradeoff to inspect |
| - | - | - |
| Sell the entire excess | Move closer to the target immediately. | Realize more gains and incur trading costs. |
| Sell part of the excess | Reduce the deviation with fewer sales. | Retain some drift and modeled active risk. |
| Keep the position for now | Defer the gain from a sale. | Continue carrying the overweight exposure. |

Restrictions and limits determine which choices are feasible. Preferences then influence which feasible choice the optimizer favors. A loss-harvesting opportunity elsewhere can also change the balance. [Tax-aware management](/advisor/tax-aware-management) explains the lot and tax assumptions behind that calculation.

For a worked example of this interaction, see [Leave room for tax-loss harvesting](/advisor/optimization-configuration#leave-room-for-tax-loss-harvesting) in the optimization configuration guides.

## Turnover and costs measure different things

A turnover limit controls the amount traded. Tilt's optimizer measures two-way turnover as the sum of absolute traded portfolio weights, excluding the cash residual. Selling 5% of account value and buying another 5% uses 10% two-way turnover in this measure.

Transaction-cost penalties influence the optimizer's choices. Reported estimated transaction costs are calculated separately, so a cost penalty and the reported cost estimate are not interchangeable. Neither an estimate nor a saved proposal establishes the eventual execution price.

## What the proposal establishes

A successful proposal gives you a candidate portfolio under the run's inputs and configuration. Check the resulting holdings, proposed trades, drift, modeled risk, tax estimates, costs, and exceptions together. An infeasible run means the attempted combination could not produce an acceptable solution; it does not establish that the model allocation itself is inappropriate.

A monitoring breach identifies an account for attention. It does not establish that an immediate rebalance is the best tradeoff, and running optimization does not execute trades. Use [reports and backtests](/advisor/reports-and-backtests) to inspect evidence before accepting a proposal.

***

Wash-sale rules may disallow a loss if substantially identical securities are bought within 30 days before or after the sale, including in the client’s other accounts, such as IRAs or a spouse’s accounts. The Platform’s wash-sale checks cover only accounts on the Platform, so confirm the client’s full position with a qualified tax professional.

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.

See [IRS Publication 550](https://www.irs.gov/publications/p550) for U.S. wash-sale rules.


# Advisor workflows
Source: https://docs.tilt.now/advisor/overview

How clients, accounts, model portfolios, and optimization proposals fit together in Tilt.

Tilt brings your client book, model portfolios, account settings, and rebalance proposals into one workspace. Use the account pages to inspect holdings and settings, and work with Tilt Agent beside them to investigate an exception or prepare a client review.

Choose your advisor organization before opening its book. For guided advisor work in chat, install **Advisor** from **Settings > Guidance Packs**. [Advisor chats](/advisor/advisor-chats) explains how to organize client reviews and recurring work.

## Your book, from household to account

Open **Clients** in the sidebar. Search by household or client name, then open the matching record. A household's **Overview** lists its members and accounts; its **Holdings** tab combines holdings across those accounts. Open a member or account to inspect its individual setup and proposals.

Open **Firm** in the sidebar to see the whole book in one place, with its holdings, history, and setup. [Review the firm](/advisor/review-the-firm) covers that page.

To [manage monitoring policies](/advisor/monitoring-policies), open **Firm → Setup → Monitoring**. Edit firm values in the dialog, then review the queue and select **Apply firm changes**. Each watch links to its model and account overrides.

![Clients page for Evergreen Advisory showing the household search, Add client and Upload clients controls, and households with account counts, model names, and values.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/evergreen-client-book.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=9adbbb03e53e6b5e9c9843533f2cf421)

Clients shows households and individual clients with their accounts, assigned models, and account values. This example uses the synthetic Evergreen Advisory practice.

## The objects you work with

| Object | What it represents | What to check |
| - | - | - |
| Client | A person or entity your organization manages. | The correct client identity and organization. |
| Household | A group of clients whose accounts you review together. | Members, accounts, and combined holdings. |
| Account | A client's holdings, portfolio composition, and account-specific settings. | Holdings freshness, primary model, portfolio weights, and restrictions. |
| Model portfolio | A shared sleeve designated for account assignment and model management. | Sleeve structure, target weights, and implementation choices. |
| Optimization proposal | A saved result for one account's holdings, portfolio, and settings. | Status, proposed holdings and trades, drift, costs, and exceptions. |
| Account backtest | A saved comparison of two tax scenarios over a historical period. | Applied Setup, comparison values, period, and hypothetical assumptions. |

A sleeve is a reusable investment building block that holds securities or other sleeves. An account can follow its primary model's allocation or combine it with additional sleeves at account-specific weights, such as 90% model and 10% Gold. The primary model still supplies inherited settings. [Build a model portfolio](/advisor/build-model-portfolio) covers the shared structure; [Tailor a client account](/advisor/tailor-account) covers account weights and preferences.

![Model portfolio and sleeves feed an assigned client account; its saved holdings and settings feed optimization; optimization returns a proposal for advisor review.](https://mintcdn.com/tilt/YNQ0-zbClB70xG-H/images/advisor/workflow.svg?fit=max\&auto=format\&n=YNQ0-zbClB70xG-H\&q=85\&s=f380028bba4aa99aebd1d4ec2629ab2a)

The advisor workflow, from a reusable model to an account proposal.

## Work on one account

On a client's page, choose the account by name. **All accounts** gives you the combined client view when the client has several accounts. An individual account opens on **Overview** and has these tabs:

| Tab | Use it to |
| - | - |
| **Overview** | See performance against the model and benchmark, drift, realized gains, recent transactions, and allocation. [Read an account's Overview](/advisor/account-overview) explains each section. |
| **Optimization** | Open the latest proposal or backtest. Select **Optimize** for a new proposal or **Backtest** to compare tax settings over a historical period. |
| **Holdings** | Inspect positions and tax lots, search for a ticker, and review cash and non-tradable assets. |
| **Setup** | Inspect the primary model, portfolio weights, sleeve implementation, and settings with their sources. |
| **History** | See who changed the account, when, and why. [See who changed an account](/advisor/see-who-changed-an-account) walks through it. |

![Okafor Family Trust on Optimization, with separate Proposal and Backtest rows, an Optimize button, and a Backtest button. Neither row has a saved result yet.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-account-optimization.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=ec947be9b12b3471ad504d9f433cf06a)

Optimization has separate Proposal and Backtest rows. Open a saved result from its row or start a run with the button beside it.

Show the chat beside the account to [ask Tilt Agent about the page you are viewing](/tilt-agent/ask-about-page). Name the account when a request could refer to more than one. For example: **"Review Maya Patel's Revocable Trust. Explain its assigned model, current holdings, and latest proposal before suggesting any changes."**

## Shared models and account preferences

Open **Models** to inspect a reusable portfolio. **Allocation** shows its sleeve targets, **Setup** shows its optimization settings, and **Accounts** shows which accounts follow it. Review those accounts before changing a shared model.

An account's **Setup** shows where its values come from. Under **Portfolio**, use **Edit portfolio** to set weights for the primary model and additional sleeves. These weights affect only this account, while shared sleeve definitions stay linked. You can also tailor the account's direct indexing, Tilts, tax settings, or constraints. Changes to sleeve implementation and settings wait in **Queued changes** until you select **Apply**. Portfolio weights and model assignment save when you confirm them, outside the queue. [Tailor a client account](/advisor/tailor-account) walks through both kinds of edits.

Use the [optimization configuration guides](/advisor/optimization-configuration) to assess interactions between settings, starting with factor bounds and tax-loss harvesting in a concentrated portfolio.

Use [account templates](/advisor/account-templates/overview) to copy selected settings into an account and review the changes before applying them. Later template edits leave the account unchanged.

To limit asset-class or custom factor exposure, [set factor exposure bounds](/advisor/set-factor-exposure-bounds) in an account, model, or firm's **Constraints** editor.

## From analysis to a trade decision

An optimization produces a saved proposal for review. Inspect its trades, target holdings, and available tax and attribution detail before deciding what to do. Sending orders to a custodian requires a linked eligible account and a separate action. Check the resulting order status before treating submission as a fill. [Review a rebalance](/advisor/review-rebalance) covers each step.

## Choose a task

> [card] [Onboard a client](/advisor/onboard-client)
>
> Set up a new client and account, then check what is ready for optimization.

> [card] [Build a model portfolio](/advisor/build-model-portfolio)
>
> Define sleeves and weights, choose implementation settings, and assign a model to an account.

> [card] [Daily briefing](/advisor/daily-briefing)
>
> Understand today's book coverage, breaches, and accounts needing attention.

> [card] [Read an account's Overview](/advisor/account-overview)
>
> See how an account performed, how far it has drifted, and its tax position.

> [card] [Review a rebalance](/advisor/review-rebalance)
>
> Check readiness, run an optimization, and inspect the saved proposal.

> [card] [Configure trade release rules](/advisor/trade-release-rules)
>
> Flag proposals for review and choose who can send them.

> [card] [Connect your custodian](/advisor/connect-custodian)
>
> Connect your firm's Alpaca keys and sync client accounts.

> [card] [See who changed an account](/advisor/see-who-changed-an-account)
>
> Inspect changes, compare saved values, and open the conversation behind a change.

> [card] [Set an inactivity logout](/advisor/inactivity-logout)
>
> Sign people out of your firm after a set time without activity.

> [card] [Require a passkey or two-step sign-in](/advisor/require-passkey-or-two-step-sign-in)
>
> Make members sign in to your firm with a passkey, a two-step code, or both.

> [card] [Set up your sign-in methods](/advisor/sign-in-with-passkey-or-two-step)
>
> Set up the passkey or two-step method a firm asks you for, and get help after a lost device.

The [Portfolio Optimization API guide](/customization/guide) covers API integration. The pages here describe advisor work in Tilt.

Understand the investment concepts behind these workflows: [optimization tradeoffs](/advisor/optimization-explained), [models and benchmarks](/advisor/models-and-benchmarks), and [tax-aware management](/advisor/tax-aware-management).

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.


# Read proposal reports and account backtests
Source: https://docs.tilt.now/advisor/reports-and-backtests

Inspect a saved proposal, run an account backtest, and compare tax settings over a historical period.

Proposal reports explain a completed optimization. Account backtests compare modeled scenarios over a period. Choose the tool that answers your question, and keep its account, inputs, and date range attached to every result. A backtest is a simulation that starts from cash, so it never shows what an account actually earned; [Account performance](/advisor/account-performance) does.

## Read a completed proposal

Open the client account's **Optimization** tab and select its dated **Proposal** link. Check the client and account below the title before reading the result. This example uses **Maya Patel's Revocable Trust** in the synthetic Evergreen Advisory practice.

| Proposal tab | Evidence to inspect |
| - | - |
| **Trades** | Proposed tickers, order sides, quantity or notional type, amounts, and reasons. |
| **Holdings** | The allocation the proposal would produce. |
| **Tax details** | Tax evidence included with the optimization result, when available. |
| **Trade attribution** | Attribution evidence explaining trades, when available. |

Ask Tilt Agent: **"For Maya Patel's Revocable Trust proposal, show the full proposed allocation, the main trades, turnover, costs, and the settings used by that run."**

![Saved proposal for Maya Patel's Revocable Trust with headline metrics, Trades, Holdings, and Tax details tabs, and proposed order amounts.](https://mintcdn.com/tilt/Nj1SDGdRgiYweBVF/images/advisor/evergreen-proposal-trades.jpg?fit=max\&auto=format\&n=Nj1SDGdRgiYweBVF\&q=85\&s=0d9e5c4fecdd5c9c96f35f21b74586bd)

The proposal page keeps the account identity, summary metrics, and detailed result tabs together.

Check the exact account and completed proposal first. The proposed holdings and trades come from position evidence; turnover, risk, and costs come from summary evidence. Settings used by the run come from its saved configuration, which may differ from the account's current settings. Ask for the relevant tax report before discussing estimated tax if executed.

For a question such as **"Why did the proposal change this ticker's weight?"**, ask Tilt Agent to inspect that ticker's decomposition and attribution evidence. A position change alone shows the outcome, not its cause. Reports describe proposed trades and estimated effects until execution is verified.

## Compare account scenarios with a backtest

One account backtest contains two scenarios that differ in one tax setting. You can run it from the account page or ask Tilt Agent to run the same comparison.

In the account interface, you start with \$1,000,000 of synthetic USD cash and rebalance monthly using the account's applied **Setup**. Tilt uses historical prices and the account's configured tax rates. Your current holdings and tax lots stay outside the simulation, and running a backtest leaves the account's holdings and orders unchanged.

### Run a comparison

1. Open **Clients**, choose the client, and select the account by name. In **Setup**, check the model, sleeves, and tax settings. Apply or discard queued changes.
2. Open **Optimization**. Select **Backtest** beside the Backtest row to open **New backtest**. Select the row itself to reopen the latest saved result.
3. Choose **Tax gamma** or **Loss threshold** and enter the comparison values.
4. Choose a **Period** of 1, 3, or 5 years and an **Ending** date. The default ending date is yesterday in UTC. Choose an earlier date to examine a historical period.
5. Select **Run backtest**. The saved backtest page opens and shows progress until both scenarios finish. You can leave and reopen it from the account's Backtest row.

![Okafor Family Trust on Optimization, with separate Proposal and Backtest rows. Callout 1 marks the Backtest row and callout 2 marks the Backtest button.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-account-optimization.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=ec947be9b12b3471ad504d9f433cf06a)

On Optimization, the Backtest row opens the latest result. Its Backtest button starts a new comparison.

1. Open the latest saved comparison from the **Backtest row**.
2. Start a new comparison with the **Backtest button**.

| Compare | What the two scenarios vary |
| - | - |
| **Tax gamma** | Gamma 0 versus the positive gamma you enter. Gamma controls tax emphasis in the optimization; it is separate from the account's tax rates. |
| **Loss threshold** | Two different harvesting thresholds, expressed as percentages, at one tax gamma. This comparison is available for long-only accounts. |

This example compares gamma 0 with gamma 1 over three years ending September 30, 2026, for Maya Patel's Revocable Trust. Gamma 1 is an example input, not a recommended setting.

![New backtest dialog with Tax gamma selected, gamma 1, a three-year period ending September 30, 2026, and numbered callouts for the comparison, period, and Run backtest.](https://mintcdn.com/tilt/g3-sE8LKMixEYbcW/images/advisor/evergreen-new-backtest.jpg?fit=max\&auto=format\&n=g3-sE8LKMixEYbcW\&q=85\&s=5654e1517735ab9ed7342c66d6bdafb8)

Choose the comparison, its values, and the historical period before selecting Run backtest.

1. Choose the comparison and enter its values.
2. Set **Period** and **Ending**.
3. Select **Run backtest**.

### Read the saved results

Check the account identity and period at the top of the page. The report includes the index return and recorded tax rates when available. Select **Hypothetical** to read the replay assumptions.

![Completed tax gamma 0 versus 1 backtest showing the account, historical period, recorded tax rates, scenario totals, and annual return comparison.](https://mintcdn.com/tilt/g3-sE8LKMixEYbcW/images/advisor/evergreen-backtest-results.jpg?fit=max\&auto=format\&n=g3-sE8LKMixEYbcW\&q=85\&s=bd6fc4830faa2238f408e7387f946f63)

The completed comparison separates whole-period dollar totals from the per-year return table.

| Report item | How to read it |
| - | - |
| Scenario dollar totals | Net gains or losses realized and tax paid or saved over the whole period. These are modeled totals, not annual amounts. |
| **Return above the index, before tax** | The scenario's annualized return minus the index's annualized return. A negative value means it trails the index; it does not by itself mean the portfolio lost value. |
| **Tax alpha** | The annualized effect of modeled taxes on returns. A negative value is tax drag. |
| **Trading costs** | The annualized reduction in return from trading costs. |
| **Return above the index, after tax and costs** | The scenario's annualized return after taxes and costs, relative to the index. |
| **Tracking error** | Variation in returns relative to the index. A predicted value is an estimate rather than a measurement against recorded index returns. |
| Difference column | The second scenario minus the first. **pp** means percentage points. |

When the run lacks index returns, the table shows **Return before tax** and **Return after tax and costs**, plus predicted tracking error. Read those return rows as portfolio returns rather than returns above an index.

The chart shows cumulative net losses harvested as a percentage of starting value. Net gains can make this signed measure negative. Read it as realized gains and losses, not portfolio value or investment return.

![Cumulative net losses harvested chart for gamma 0 and 1, with the scenario legend and assumptions about the historical period, terminal sales, and trading costs.](https://mintcdn.com/tilt/g3-sE8LKMixEYbcW/images/advisor/evergreen-backtest-chart.jpg?fit=max\&auto=format\&n=g3-sE8LKMixEYbcW\&q=85\&s=eedb57778486a80d3faf2d1d2b623198)

Use the chart to compare cumulative net losses and read the assumptions below it before interpreting the result.

One historical period is insufficient to choose a tax setting. The backtest leaves the portfolio unsold at the end, so remaining unrealized gains can create tax on a later sale. For modeled tax savings, Tilt assumes losses offset other gains in the same period at the account's configured rates. Tax rules can limit how much net loss you use each year, and harvesting lowers cost basis. Check those assumptions against the client's circumstances before interpreting the savings. Missing recorded data remains unavailable.

### Repeat the comparison

Select **New backtest** on a saved backtest page. The dialog keeps that backtest's comparison values, period, and ending date. Running it again uses the account's currently applied Setup, so the same dates do not guarantee the same result.

After you change Setup, an older backtest can show **Setup changed since this backtest**. Read those results as an analysis of the earlier Setup. The index-return label becomes **the index used for this backtest** rather than attributing the saved return to the current benchmark.

### Run it with Tilt Agent

Ask: **"For Maya Patel's Revocable Trust, run a three-year backtest ending September 30, 2026, comparing tax gamma 0 against 1. Show me the saved comparison."**

The agent-run backtest becomes the account's latest saved backtest. Use **Open** on its comparison card to visit the results page. For a follow-up, ask about that saved result, for example: **"Explain the tax difference using the recorded gains, losses, and tax rates."**

Open the saved backtest and [ask about it in chat](/tilt-agent/ask-about-page). Check **Looking at** above the message input before asking a follow-up about the comparison.

### If you cannot run or read a backtest

| Condition | Next action |
| - | - |
| Queued Setup changes | Apply or discard them before starting from the account page. |
| Missing Setup or tax gamma | Check the model, sleeves, and effective tax gamma in Setup. |
| Tax-deferred or tax-exempt account | The Backtest row explains that the account does not pay capital gains tax. These comparisons do not apply. |
| No **Loss threshold** option | Use **Tax gamma** on a long/short account. |
| Running | Reopen the existing backtest to check progress. Starting another comparison creates a separate backtest. |
| Failed | Read the failure reason before deciding whether to start another run. |
| Identical scenario results | Treat this as a valid no-difference result for the chosen inputs and period. |

The concept pages explain [optimization tradeoffs](/advisor/optimization-explained), [reference portfolios](/advisor/models-and-benchmarks), and [tax estimates](/advisor/tax-aware-management).


# Require a passkey or two-step sign-in for your firm
Source: https://docs.tilt.now/advisor/require-passkey-or-two-step-sign-in

Make everyone in your firm sign in with a passkey, enter a two-step code, or both. See who isn't set up yet, and reset a member's methods after a lost device.

Your firm can ask for more than the usual sign-in. These rules apply to your firm only: each member's personal workspace and their other organizations sign in as before.

| Rule | What members do |
| - | - |
| **Require a passkey** | Sign in to the firm with a passkey: Touch ID, Face ID, or the device's PIN. A passkey works only on Tilt's own site, so a fake sign-in page can't use it. |
| **Require two-step sign-in** | After signing in, also enter a code from a method the firm allows: an authenticator app, a text message, or either. |

With both rules on, members do both: they sign in with a passkey and also enter a two-step code. A passkey is a way to sign in, so it never counts as the two-step code.

Every firm starts with both rules off. Only an organization owner can change them, and the owner passes the same check before Tilt saves a new rule, so the owner can't lock themselves out.

## 1. Choose the rules

Open **Settings > Security** in your firm. **Security** appears under **Organization** in the Settings menu. Members who aren't owners see each rule read-only, with **Only an organization owner can change this.**

* To require a passkey, check **Require a passkey to sign in to this firm (Touch ID, Face ID or a PIN)** under **How members sign in**.
* To require two-step sign-in, check **Require two-step sign-in** under **Two-step sign-in**, then choose the **Allowed methods**: **Authenticator app**, **Text message**, or both. Tilt starts with **Authenticator app**, and at least one method stays checked.

Text messages are the weaker method. Someone who talks a phone carrier into moving a member's number to their own SIM card gets that member's codes, so prefer an authenticator app and allow text messages only when members need them. Tilt texts codes to US, Canadian and UK mobile numbers.

![How members sign in, with Require a passkey to sign in to this firm (Touch ID, Face ID or a PIN) unchecked. Two-step sign-in, with Require two-step sign-in checked and the allowed methods Authenticator app and Text message both checked; Text message reads Weaker: a stolen phone number gets the codes. Ask members again is set to After the inactivity logout. A line reads 4 members aren't set up yet, and the open list shows four blurred emails, each with Needs a two-step method. A Save changes button sits below.](https://mintcdn.com/tilt/6xkyJibTs_pja0DA/images/advisor/security-sign-in-rules-owner.jpg?fit=max\&auto=format\&n=6xkyJibTs_pja0DA\&q=85\&s=15b06faadd2b23c82a0fc034012ce8b2)

An owner turning on two-step sign-in for a demo firm, Maple Ridge Advisors, before saving, with See who open. Test-account emails are blurred.

### Ask members again

**Ask members again** sets how long a member's passkey or two-step check counts before the firm asks for it again. It covers both rules.

| Choice | The firm asks again |
| - | - |
| **After the inactivity logout** | When the firm's [inactivity logout](/advisor/inactivity-logout) signs the member out. |
| **Every 24 hours** | A day after the member's last check, or after the inactivity logout, whichever comes first. |
| **Every 7 days** | A week after the member's last check, or after the inactivity logout, whichever comes first. |

Coming back after the inactivity logout always asks again. While the inactivity logout is **Off**, **After the inactivity logout** isn't offered, so choose **Every 24 hours** or **Every 7 days**.

Each sign-in has its own checks. A member who signs in on a second browser, or in [Tilt for Mac](/tilt-agent/tilt-for-mac), confirms it's them there too.

### See who isn't set up yet

While either rule is checked, the page counts the members who don't have what the rules on the page need, for example **4 members aren't set up yet**. Select **See who** to list them by email, each with what they need: **Needs a passkey**, **Needs a two-step method**, or both. The count follows the page as you change the rules, so you see who a change affects before you save it. **Every member is set up.** means nobody is missing anything.

Only methods set up for this firm count. The first time a rule goes on, every member shows as not set up, you included.

## 2. Confirm it's you and save

Select **Save changes**. Before Tilt saves a rule you're turning on, or a change to the allowed methods, it asks you to pass a check the new rule accepts, for this firm, in the last 10 minutes. The page runs the check in place:

* **Require a passkey:** add a passkey for the firm with **Add a passkey**, or use the one you have.
* **Require two-step sign-in:** set up an allowed method for the firm with **Set up an authenticator app** or **Set up text message codes**, or enter a code from the one you have.

Your first method for the firm starts with a code Tilt emails you. Once the check passes, Tilt saves your settings. Turning a rule off, or changing only **Ask members again**, needs no check.

Each save adds a **Changed settings** entry to the firm's History, with the old and new value of each setting and the owner who saved it. Select **Open History** on the Security page to see it.

## What members see

The next time a member opens the firm, Tilt shows the firm's sign-in page instead. It asks them to add a passkey or set up two-step sign-in for the firm, starting with a code Tilt emails them, or to confirm it's them with a method they already set up. Right after they sign in to Tilt, the same page asks for the firm, with **Not now** to skip it until they open the firm. [Sign in to a firm that requires a passkey or two-step sign-in](/advisor/sign-in-with-passkey-or-two-step) walks members through it.

Methods belong to one person in one firm. A member's authenticator app, phone and passkeys for your firm never count at another firm, and theirs from another firm never count at yours.

When you turn a rule off or stop allowing a method, members keep the methods they set up. They can remove them in **Settings > Sign-in methods**. If you turn the rule back on, those methods count again.

## Reset a member's lost device

While your firm requires a passkey or two-step sign-in, or members still have methods for it, **Members' sign-in methods** on the Security page lists each member's passkeys and two-step methods for your firm: the kind of method, a passkey's name, when it was added and last used, and the last two digits of a phone. A member without what the rules need shows **Not set up**. Methods a member set up for another organization never show here.

To reset a member who lost their device:

1. Select **Reset** beside the member.
2. Read the dialog and select **Reset**. If you haven't confirmed it's you in the last 10 minutes, Tilt asks first: with a code from your email when the firm requires neither rule, otherwise with your own method for the firm.

The reset removes the member's sign-in methods for your firm only. Their sign-in to other organizations doesn't change. Tilt emails them about it, and the firm's History records **Reset a member's sign-in methods**. While the firm requires a passkey or two-step sign-in, they set up a method again the next time they open it, starting with an emailed code.

![Members' sign-in methods for Maple Ridge Advisors. Two members show a Not set up badge and No sign-in methods set up yet. One member's row reads Two-step: Authenticator app, added Oct 28, 2026, last used Oct 28, 2026, with a Reset button. The owner's own row has an Owner badge, the same kind of authenticator app line, and no Reset button.](https://mintcdn.com/tilt/6xkyJibTs_pja0DA/images/advisor/security-members-sign-in-methods.jpg?fit=max\&auto=format\&n=6xkyJibTs_pja0DA\&q=85\&s=6ef5040327d71f593e7ad8876be2d723)

Members' sign-in methods in Maple Ridge Advisors. Test-account emails are blurred.

A member who still has another method for your firm can remove the lost one themselves in **Settings > Sign-in methods**.

## If you're the firm's only owner

You can't reset your own methods. Another owner of your firm can. If you're the only owner and you've lost the device with your methods, contact Tilt support. Tilt support resets your methods for this firm only, the firm's History shows **Tilt support** as who made the reset, and Tilt emails you about it.

## API keys, connected apps and Tilt Agent

The rules apply to people signed in to Tilt. These keep working in the firm whether or not a member meets the rules:

* Requests made with a Tilt API key.
* Apps already connected to Tilt, such as Claude or ChatGPT.
* Automations and other [background jobs](/tilt-agent/background-jobs).
* Tilt Agent replies that had already started.

Creating a Tilt API key for the firm, or connecting a new app to it, needs a sign-in that meets the firm's rules. So does opening the firm in Tilt to start a new chat.

## Ask Tilt Agent

Tilt Agent reads your firm's rules and explains them. For an owner, it also says how many members aren't set up yet; it never says who, and it never reads anyone's methods. Ask, for example, **"Does our firm require two-step sign-in?"** or **"How many people still need to set up two-step sign-in?"**

Tilt Agent never changes these settings itself. Ask it to turn a rule on or off, or to change the allowed methods or **Ask members again**, and it prepares a review card with the current and new value of each setting. Nothing changes until an owner applies the card in Tilt, in the firm. Applying a card that turns a rule on needs the same check from the last 10 minutes; without one, Tilt refuses it, and **Settings > Security** asks for the check and saves the same change.

Tilt Agent never resets a member's methods. Never paste a sign-in, authenticator app, or text message code into chat. Enter codes only on Tilt's own screens.


# Review a rebalance
Source: https://docs.tilt.now/advisor/review-rebalance

Check an account, request optimization, and review the saved proposal before any trade decision.

Use a rebalance review to compare a client account's current holdings with its assigned portfolio. This example follows **Maya Patel's Revocable Trust** and the **Growth** model in the synthetic Evergreen Advisory practice. An optimization saves proposed holdings and trades for your review.

## 1. Check account readiness

Open the client from **Clients** and select the account by name. In **Holdings**, inspect saved positions, tax lots, and cash. In **Setup**, check the assigned model, sleeves, and settings. Apply or discard queued setup changes before requesting a run. The **Optimization** tab identifies missing holdings, model, or sleeves and offers a link to the relevant tab.

Ask Tilt Agent: **"Check whether Maya Patel's Revocable Trust is ready for optimization. Show its saved holdings, assigned model, and any blockers. Do not run an optimization yet."**

Check the client and account identity, holdings freshness, assigned model, and effective allocation. Resolve any missing holdings, assignment, or configuration blocker before proceeding. If an earlier completed proposal is still current, ask to review it first.

![Okafor Family Trust on Optimization, with separate Proposal and Backtest rows and their Optimize and Backtest buttons. Neither row has a saved result yet.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/northwind-account-optimization.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=ec947be9b12b3471ad504d9f433cf06a)

Use the Proposal row to review a rebalance or Optimize to request one. The separate Backtest row compares tax settings over a historical period.

To compare tax settings before changing Setup, [run an account backtest](/advisor/reports-and-backtests#compare-account-scenarios-with-a-backtest).

## 2. Request an optimization

When the saved inputs are right, select **Optimize** on the **Optimization** tab, or ask: **"Run an optimization for Maya Patel's Revocable Trust using its saved Growth model and current settings."** Either action requests a run. If the account or inputs changed since your readiness check, inspect them again before submission.

Tilt Agent follows the run until it finishes and retains the proposal. A pending run has no result to review yet. If the run fails, inspect the stated reason before deciding whether to request another run.

The account page follows the job's status. When a run started there completes while you are still on that page, Tilt opens its proposal. You can also open the dated **Proposal** link yourself.

## 3. Review the saved proposal

Check the client and account below the proposal's title. Review the headline metrics, then open **Trades** for order sides, tickers, types, and amounts, and **Holdings** for the proposed target. **Tax details** and **Trade attribution** appear when the result includes that evidence. Scroll through the full lists before making a decision.

![Maya Patel's proposal with a Custodian trading unavailable notice, NAV and turnover metrics, Trades, Holdings, and Tax details tabs, and the beginning of the proposed order list.](https://mintcdn.com/tilt/Nj1SDGdRgiYweBVF/images/advisor/evergreen-proposal-trades.jpg?fit=max\&auto=format\&n=Nj1SDGdRgiYweBVF\&q=85\&s=0d9e5c4fecdd5c9c96f35f21b74586bd)

Maya's saved proposal shows summary metrics and proposed trades. The notice identifies a missing custodian link before orders can be sent.

Ask: **"Explain this proposal's turnover, tax impact, and constraints using its saved run settings."** Settings used by a completed run can differ from the account's current setup. [Read proposal reports](/advisor/reports-and-backtests) for the evidence behind those answers.

A completed proposal can have no trades. That is a valid no-action outcome. If Tilt Agent provides a link to the account's proposal review view, opening it lets you inspect the persisted proposal. It does not approve or execute it.

## Review the morning Trading queue

Open **Trading** > **To review** to work through saved account proposals. Start here when the morning proposals are ready; you do not need to request another optimization to review them.

For example, Tyler reviews all proposals at first and uses the flags to prioritize attention. As a junior colleague takes on ordinary proposals, the colleague can send those within their trading permissions. Tyler reviews and sends flagged proposals for which the colleague lacks eligibility. Each sender makes their own decision on the whole account proposal.

Open a proposal and inspect its flags, contributing trades, measured values, thresholds, evidence dates, and coverage limitations. Everyone with access to the proposal sees its flags, including eligible senders. See the [condition reference](/advisor/trade-release-conditions) for definitions.

Select **Details** beside the proposal's flag summary. Expand **Calculation and sources** to inspect the evidence for a condition.

![Trade release flags details showing Large security trade, SPY sell, value \$6,000, threshold greater than \$5,600, and proposal orders as the source.](https://mintcdn.com/tilt/xsUklhYBvklVynuI/images/advisor/trade-release-flag-details.jpg?fit=max\&auto=format\&n=xsUklhYBvklVynuI\&q=85\&s=a25064dea7b0bb1a1fc7d137c27cf976)

In a demo firm, a $6,000 SPY sell matches the saved rule for security trades over $5,600.

A **Could not evaluate** flag means Tilt lacks enough evidence to settle a rule. Review the missing evidence before deciding to send. A known-false condition settles an AND rule as not matched even if another condition lacks evidence. Only a sender eligible under every matched and unresolved rule can send. Eligible senders can investigate outside Tilt; they do not need to enter an explanation or complete a separate acknowledgment.

## 4. Make a separate trade decision

Reviewing the proposal leaves its orders unsubmitted. Custodian trading requires an eligible linked account and access to the custodian connection. If Tilt shows **Custodian trading unavailable**, resolve the stated connection or account-link issue before sending orders.

Review the exact account, complete trade list, and any custodian warnings before selecting **Send** and confirming. You authorize the whole account proposal, rather than individual orders.

For organization optimizer proposals, review the [trade release rules](/advisor/trade-release-rules) and flags before using **Send**. You need trading permission and eligibility under every matched or unresolved rule. Confirm the whole account proposal yourself; there is no separate approval another person can redeem later. Inspect each account's outcome after a multi-account send.

Tilt checks current rules, membership, evidence, proposal contents, and destination before accepting each account's send. If relevant details changed, review and confirm again. One account can remain blocked while another proceeds.

An accepted send means the order engine accepted that account's batch. Inspect broker submission and fill statuses to establish what reached the broker and what executed. Later rule or membership changes can block subsequent sends, but do not cancel an accepted batch or its sell-then-buy continuation.

Before interpreting a proposal, read [how optimization makes tradeoffs](/advisor/optimization-explained) and [tax-aware portfolio management](/advisor/tax-aware-management).


# Review the whole firm on the Firm page
Source: https://docs.tilt.now/advisor/review-the-firm

See your firm's book, holdings, history, and setup in one place.

The **Firm** page shows your whole book above its households, clients, and accounts. Open **Firm** in the left sidebar.

Above the tabs, a line sums up the firm: what it manages across its households, how many accounts it has, and how many accounts need attention. Select the attention count to open **Clients**, which lists the households and clients that need attention first.

> [!NOTE]
>
> The attention count comes from the latest drift check, and it matches the count in the [daily briefing](/advisor/daily-briefing). It includes every account the check flagged, including stale accounts and accounts the check skipped. **Clients** lists each account's own reasons, such as model drift, cash to deploy, or no model, so the accounts it flags may not match the count.

The page has three tabs: **Holdings**, **History**, and **Setup**.

## Holdings

**Holdings** lists every security in the book with its value, weight, quantity, and how many clients hold it. Search by ticker, or select a column heading to sort by it; select it again to reverse the order. On a phone, choose the order from the menu above the list.

Holdings counts positions accounts hold directly. A position in an ETF or fund appears as that fund. Cash is counted in the firm's total above the tabs.

## History

**History** lists every recorded change across the firm: its households, clients, accounts, models, sleeves and Tilts, and the firm's **Setup** and **Security** settings. The **About** column names what each row was about, and **Kind** says whether that is an account, a model, the firm, and so on. Automation runs that changed nothing are counted above the list.

Narrow the list by what an entry is about, by who acted (including Tilt Agent acting for that person), and by a range of days. To read a row, see [See who changed an account and why](/advisor/see-who-changed-an-account).

## Setup

**Defaults for models and accounts** holds the settings every model and account uses unless it sets its own: **Tax**, **Transactions**, **Optimization**, **Constraints**, and **Rules**, the same groups an account's and a model's **Setup** show. Each row summarizes its values; select one to edit it.

The firm sets two more things for every account: the minimum buy and the limit band, in **Transactions**, and the automatic corporate-action rules, in **Constraints**. **Account templates**, the last row in the section, holds [reusable account settings](/advisor/account-templates/overview); firm owners and editors can create, edit, or archive templates.

**Monitoring**, in the same defaults section, opens a dialog with **Model drift watch**, **Sleeve tracking watch**, **Cash band watch**, and **Factor exposure watch**. Edit the firm values and select **Done** to return to Setup; edits remain queued until you select **Apply firm changes**. Each watch links to its model and account overrides and account tests. [Manage monitoring policies](/advisor/monitoring-policies) covers the editor. Scheduled assignments and their signals remain in **Automations**.

**Access and approvals** holds what only organization owners can change. Owners can [change trade release rules](/advisor/trade-release-rules) in **Trade release rules**. **Sign-in security** shows the firm's [inactivity logout](/advisor/inactivity-logout); select it to open **Settings > Security**, where only organization owners can change it and can [require a passkey or two-step sign-in](/advisor/require-passkey-or-two-step-sign-in).

Settings, firm monitoring, account-template definitions, and trade release rule edits wait in **Queued changes** until you select **Apply firm changes**. Remove a row to undo its change, or select **Discard all** to abandon the queue. Successful saves leave the queue; failed changes remain for review. Saving template definitions leaves accounts unchanged. If you leave **Setup** with unapplied changes, Tilt asks whether to apply or discard them.

A setting on a model or account page that comes from the firm shows a badge; select it to open that group in **Setup**. To add conditional rules or restrictions, see [Set conditional rules and preview their effect](/advisor/configuration-and-rules).


# See who changed an account and why
Source: https://docs.tilt.now/advisor/see-who-changed-an-account

Use History to inspect changes, compare saved values, and open the conversation behind a change.

Use **History** to investigate a change to a client account, review who acted, and follow the conversation behind it. History also appears on client, household, and model pages, and on the **Firm** page for every change across the firm.

## 1. Open History for the right scope

Open **Clients**, find the client or household, and choose the scope you want to review. Then select **History**. For the whole firm, open **Firm** in the left sidebar, then **History**.

| Scope | Where to look | What the view includes |
| - | - | - |
| One account | Select the account by name, then **History**. | Entries for that account. When the client has only one account, this view also includes client-level entries. |
| A client with several accounts | Select **All accounts**, then **History**. | Client-level entries and entries for the client's accounts. |
| A client without accounts | Open the client, then **History**. | The client's recorded history, even after the last account has been deleted. |
| A household | Open the household, then **History**. | Entries for the household, its clients, and their accounts. |
| A model | Open the model from **Models**, then **History**. | Entries for that model. |
| The firm | Open **Firm**, then **History**. | Activity across the firm's households, clients, accounts, models, sleeves and Tilts, and changes to the firm's **Setup** and **Security**. Select **Include routine activity** to see automation runs that changed nothing. Filter by what an entry is about, who acted (including Tilt Agent acting for them), and a range of days. |

Check the name above the view before interpreting a row. An entry appears on the objects it concerned when it was recorded. Moving a client to another household does not move earlier entries to the new household.

## 2. Read the row

History lists the newest entries first, grouped by day. Dates and times use your browser's local time zone. Scroll down to load older entries automatically.

For a row that groups several records, select **View operation** to inspect the individual changes. Select **Show more records** to load the rest, or **Collapse operation** to return to the summary. To include automation runs that changed nothing, select **Include routine activity** above the list.

On a wide screen, read the columns from left to right:

| Column | How to read it |
| - | - |
| **Time** | When the action happened, under its day heading. |
| **Applies to** | The client or account concerned on a household view. Client-wide History labels this column **Account**, and the firm's History labels it **About**, with a **Kind** column beside it, such as *Model*. Account and model views omit the column because the page supplies the scope. |
| **What happened** | The action and, when present, the fields it changed. An arrow reads as old value → new value. |
| **By** | The person who acted, **Tilt Agent** with the person it acted for, or **Tilt** for a system action. |
| **Source** | **Conversation** when you can open the conversation behind the action, **Private conversation** when you cannot, or a dash when there is no conversation reference. |

![Okafor Family Trust with History selected. The table shows Time, What happened, By, and Source. The latest Changed settings row lists three tax fields and a Show all 4 changes button. Source shows a dash for these direct app changes.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/history-account.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=92d6c9a30d65a3650e959fb177ca936f)

History for Okafor Family Trust, an account in the synthetic Northwind Family Office practice. The latest entry has four changed fields; three appear in the compact row. Advisor email addresses are blurred.

On a narrow screen, the same information appears as a list under each day. Conversation links read **From a conversation**.

If the view says **No history yet.**, there are no recorded entries for that scope. See [History coverage](/advisor/history-coverage) before treating an empty view as evidence that nothing happened.

## 3. Inspect every changed field

Under **What happened**, select **Show all N changes** when the row contains more fields than it displays. If a value is shortened, select **Show the full change** or **Show the full changes**.

The row expands in place to show every listed field with its complete **Before** and **After** values, including multiline lists and objects. **not set** means the value was absent or empty; switches read **on** and **off**. Select **Show less** to return to the compact row.

![Expanded Okafor Family Trust History entry showing Before and After values for Tax gamma, Long term rate, Short term rate, and Ordinary income tax rate, followed by Show less. Advisor email addresses are blurred.](https://mintcdn.com/tilt/uFh1Bh8VY4IIXmxF/images/advisor/history-changes-expanded.jpg?fit=max\&auto=format\&n=uFh1Bh8VY4IIXmxF\&q=85\&s=04eb7576ef923443b09e085080b8243f)

The expanded entry reveals the fourth field, Ordinary income tax rate, changing from 0.45 to 0.47. Show less returns to the compact row.

A proposal or automation entry can describe a decision or outcome without listing changed settings. Read the action as well as any field values. For example, **An automation ran, no changes** records a completed check that made no changes.

## 4. Open the conversation behind the change

Select **Conversation** in **Source**, or **From a conversation** in the narrow layout. Read the request and review discussion alongside the row's saved changes.

An entry remains visible even when you cannot open its conversation. In that case, the table says **Private conversation**; the narrow layout says **From a conversation you don't have access to**. History does not grant access to the conversation. A dash in **Source** does not mean the action had no cause; direct app actions and system jobs need not have a conversation.

For supervision, check [what History records and what it leaves out](/advisor/history-coverage). To review the trade decision itself, follow [Review a rebalance](/advisor/review-rebalance).

## Review future changes in chat

To receive summaries of future changes in chat, [create an event automation](/tilt-agent/review-changes-automation). Keep using History to inspect the saved before and after values behind a change.


# Set factor exposure bounds
Source: https://docs.tilt.now/advisor/set-factor-exposure-bounds

Set allocation or custom factor limits in the app for an account, model, or firm.

Use **Factor exposure bounds** in **Constraints** to limit an optimized portfolio's exposure to an asset-class type or a custom factor. You can set these bounds in the app for an account, model, or firm. An exposure bound controls the weighted exposure across holdings; an asset bound controls one ticker's weight.

> [!NOTE]
>
> Custom-factor upload is in development. You can configure bounds for built-in factors and custom factors already configured for your organization. Contact the [Tilt team](mailto:contact@tilt.now) to request a new custom factor.

## 1. Open Constraints at the intended scope

| Scope | Location |
| - | - |
| One account | **Clients → client → named account → Setup → Settings → Constraints** |
| Model | **Models → model → Setup → Constraints** |
| Firm defaults | **Firm → Setup → Constraints** |

On a client page, select a named account rather than **All accounts** to see **Setup**. Scroll to **Factor exposure bounds** in the Constraints editor.

Check the inherited values before editing. A non-empty account factor-bound list replaces the model or firm's list as a whole. A model list replaces the firm's list. Keep the factors you still need when creating a more specific list.

## 2. Add a factor and its bounds

Click **Add factor bound** and enter the exact factor name in **Factor**. For equity exposure, use `asset_allocation_equity`.

Tilt also supplies allocation factors for fixed income, commodity, currency, alternative, cash, private equity, crypto, and unknown exposure. The [built-in factor reference](/customization/factor-bounds#built-in-allocation-factors) lists their exact names and data requirements.

Enter a number in each of the four bound fields. This illustrative equity range allows 50% to 70% absolute exposure and a difference of −3 to +3 percentage points from the optimization benchmark:

| Field | Enter | Meaning |
| - | - | - |
| **Min** | `0.50` | At least 50% equity exposure. |
| **Max** | `0.70` | At most 70% equity exposure. |
| **Min active** | `-0.03` | At most 3 percentage points below the benchmark's equity exposure. |
| **Max active** | `0.03` | At most 3 percentage points above the benchmark's equity exposure. |

> [!NOTE]
>
> Factor-bound fields use the factor's units as entered. For allocation factors, enter fractions such as `0.50` for 50%. For an existing custom score, enter values on its configured loadings' scale.

Both ranges apply together. With 60% benchmark equity exposure, the illustrative active range permits 57% to 63% equity exposure, which also falls within the absolute range. Choose ranges that fit your mandate and the account's other constraints.

Use the optimization benchmark for the active comparison. A monitoring policy can use a different benchmark; [Models and benchmarks](/advisor/models-and-benchmarks) explains the references.

### Use an existing custom factor

Enter the exact name of a custom factor already configured for your organization. Confirm its availability, loading scale, and direction with the Tilt team before setting bounds. Adding its name in this editor does not create the factor or its asset loadings.

Custom-factor upload is in development. The [API guide](/customization/configure-factor-bounds#custom-factor-uploads-in-development) documents the upload format and replacement behavior for that work. Contact the team to request a factor while self-service upload is in development.

Monitoring's **Size** factor does not establish optimizer compatibility. Large-cap, mid-cap, and small-cap buckets require defined custom loadings; the built-in allocation factors do not include those buckets. A continuous Size score and a percentage allocation to a bucket measure different things. See [Size and capitalization buckets](/customization/factor-bounds#size-and-capitalization-buckets).

Contact the [Tilt team](mailto:contact@tilt.now) for another Tilt-supplied factor or help defining custom loadings. Include the exposure definition, units, asset universe, intended ranges, and active benchmark. [Request a new factor](/customization/factor-bounds#request-a-new-factor) lists the details to send.

## 3. Review and apply the change

For an account or model, click **Queue changes** to close the editor. Firm edits queue as you make valid changes. Open **Queued changes**, check the target scope and complete factor-bound list, then click **Apply** to save or **Discard all** to abandon the draft.

Reopen **Constraints** after saving and confirm the factor names and bounds. On an account or model, use **Use the inherited bounds** to return to the broader scope's list, then queue and apply that change. Removing the last local factor row also restores inheritance; check the resulting list before applying.

## 4. Optimize and inspect the proposal

After applying account changes, open the account's **Optimization** tab and run **Optimize**. Saving bounds changes optimization inputs. It does not run optimization or place trades.

Inspect the proposed holdings and factor exposures against both ranges. If the run is infeasible, review the absolute and active limits together with cash requirements, position limits, and trading restrictions. [How optimization makes tradeoffs](/advisor/optimization-explained) explains their interaction; [Review a rebalance](/advisor/review-rebalance) covers reviewing the resulting proposal.

For exposure alerts and oversight policies, use [Manage monitoring policies](/advisor/monitoring-policies).


# Sign in to a firm that requires a passkey or two-step sign-in
Source: https://docs.tilt.now/advisor/sign-in-with-passkey-or-two-step

Set up a passkey, an authenticator app or text message codes for a firm that asks for them, confirm it's you later, and get help after a lost device.

A firm's owner can [require a passkey or two-step sign-in](/advisor/require-passkey-or-two-step-sign-in) for that firm. You then set up what the firm asks for, once, and confirm it's you with it when the firm asks. The rules apply to that firm only. Your personal workspace and your other organizations sign in as before.

| The firm requires | You use |
| - | - |
| A passkey | A passkey for the firm, with Touch ID, Face ID or your device's PIN. |
| Two-step sign-in | A code from an authenticator app on your phone, or a code Tilt texts you, whichever the firm allows. |

## 1. Set up a method the first time

When you open a firm whose rules you don't meet yet, Tilt shows the firm's sign-in page: **Add a passkey**, or **Set up two-step sign-in**. Right after you sign in to Tilt, the same page asks for the firm. **Not now** skips it for now; opening the firm asks again.

![Page titled Set up two-step sign-in reading Maple Ridge Advisors requires two-step sign-in. Set up an authenticator app or a phone for text message codes for Maple Ridge Advisors to keep working there. Below, a note reads Use an app on your phone, such as Google Authenticator or 1Password, that shows a new 6-digit code every 30 seconds, above a Set up an authenticator app button, a Get codes by text message instead link, and a Choose another workspace link.](https://mintcdn.com/tilt/6xkyJibTs_pja0DA/images/advisor/firm-set-up-two-step.jpg?fit=max\&auto=format\&n=6xkyJibTs_pja0DA\&q=85\&s=b29dcb5717e0b0ea90b08bcf4a3c61ae)

The sign-in page of a demo firm, Maple Ridge Advisors, that requires two-step sign-in and allows an authenticator app or text messages.

1. Choose what to set up: **Add a passkey**, **Set up an authenticator app**, or **Set up text message codes**. When the firm allows both two-step methods, the page starts with the app; select **Get codes by text message instead** to use your phone.
2. Confirm it's you with a code Tilt emails you, when the page asks. Your first method for a firm always starts with an emailed code. If you signed in to Tilt with an emailed code in the last 10 minutes, that code counts and Tilt skips this step.
3. Finish the setup:
   * **A passkey:** select **Add a passkey** and confirm with Touch ID, Face ID or your device's PIN.
   * **An authenticator app:** scan the QR code with an app such as Google Authenticator or 1Password, or select **Can't scan? Enter this key** and type the key into the app. Enter the 6-digit code the app shows and select **Turn on**.
   * **Text messages:** enter your mobile number, then the 6-digit code Tilt texts you, and select **Turn on**. Tilt texts codes to US, Canadian and UK mobile numbers.

Finishing the setup counts as confirming it's you, and Tilt opens the firm. When the firm requires both rules, it asks for the passkey first and the two-step method next.

Text messages are the weaker method: someone who takes over your phone number gets your codes. Use an authenticator app when your firm allows one.

## 2. Confirm it's you when the firm asks

The firm asks again when its **Ask members again** setting runs out, when you come back after the firm's [inactivity logout](/advisor/inactivity-logout), and on every new sign-in. Each browser you sign in with, and Tilt for Mac, asks on its own.

* **Passkey:** select **Use your passkey** and confirm with Touch ID, Face ID or your device's PIN.
* **Authenticator app:** enter the code your app shows for Tilt and the firm, then select **Continue**.
* **Text message:** select **Send a code**, then enter the code. When you have both an app and a phone for the firm, the page starts with the app; select **Text me a code instead** to switch.

## Each firm has its own methods

A passkey, authenticator app or phone you set up for one firm counts for that firm only.

* **Authenticator apps:** the app shows one entry for each firm, under **Tilt**, with your email and the firm's name. Use the entry for the firm you're opening.
* **Passkeys:** a member of two firms that each require a passkey has a passkey for each. Your password manager shows one entry per firm, with your email and the firm's name. Any of your passkeys signs you in to Tilt with **Sign in with a passkey** on Tilt's sign-in page, and it counts as the passkey check for its own firm. Opening the other firm asks for that firm's passkey.
* **Phones:** the same phone number at two firms is set up and confirmed separately for each.

## Manage your methods

Open **Settings > Sign-in methods**, in the **Personal** group. It appears once a firm asks you for a method, or while you still have one. Each firm that asks, or where you still have a method, has its own section, and the firm you opened the page in comes first.

* Add another method, or remove one. Removing a method, or adding one when you already have a method for the firm, needs a check with one of your methods for that firm from the last 10 minutes. The page asks for it when you need one.
* An owner can't remove their last passkey for a firm that requires one.
* When a firm stops asking for a method, yours stays listed so you can remove it. A passkey you keep still signs you in to Tilt.

Tilt emails you when a method for a firm is added to or removed from your account.

![Two sections of Sign-in methods. Maple Ridge Advisors requires two-step sign-in: Authenticator app, added Oct 28, 2026 and last used Oct 28, 2026, with a Remove button, and Text message, not set up, with a Set up button. Harbor Lane Wealth requires a passkey to sign in: one passkey added Oct 28, 2026 with a Remove button, then a Passkey name box and an Add another passkey button.](https://mintcdn.com/tilt/6xkyJibTs_pja0DA/images/advisor/sign-in-methods-by-firm.jpg?fit=max\&auto=format\&n=6xkyJibTs_pja0DA\&q=85\&s=615a4aa577fe44247e035c065845d2ee)

Settings > Sign-in methods for a member of two demo firms. Maple Ridge Advisors has their authenticator app; Harbor Lane Wealth has their passkey.

## Passkeys work on tilt.now

Tilt's passkeys belong to tilt.now, and a passkey works only on the site it was made for. On tilt.io and app.tilt.io, the page links to the same page on tilt.now, where you add or use your passkey.

## Tilt for Mac

[Tilt for Mac](/tilt-agent/tilt-for-mac) asks each firm for its own checks when you open the firm in the Mac app. Checks you passed in your browser don't count there.

* **Two-step sign-in:** enter your authenticator app code or a texted code in the Mac app. You can also set up an authenticator app or a phone there, starting with an emailed code.
* **After the inactivity logout:** sign in to the firm again with **Email me a code**, or with **Continue with Google** when your Tilt account signs in with Google. Google's sign-in opens in your browser.
* **Require a passkey:** in Tilt for Mac 1.30.1 or newer, select **Continue in your browser** when the firm asks for your passkey, or when its sign-in page asks you to add one. Your browser opens so you can use your passkey for the firm, or add one first, and then you're back in the Mac app. If your browser isn't signed in to Tilt as you, sign in there first. The check counts for the Mac app only. An older Mac app asks you to [update it](/tilt-agent/tilt-for-mac#updates) first.

## If you lose your device

Ask an owner of the firm to reset your sign-in methods for that firm in **Settings > Security**. The reset removes your methods for that firm only, and Tilt emails you about it. The next time you open the firm, you set up a method again, starting with an emailed code.

* If you still have another method for the firm, you can remove the lost one yourself in **Settings > Sign-in methods**.
* If the device held methods for several firms, ask an owner of each firm. A reset at one firm doesn't change your methods at another.
* If you're the firm's only owner, contact Tilt support.

Never paste a sign-in, authenticator app or text message code into chat, Tilt Agent included. Enter codes only on Tilt's own screens.


# Tailor a client account
Source: https://docs.tilt.now/advisor/tailor-account

Combine a primary model with additional sleeves, set account-specific weights, and customize holdings, tilts, and settings.

Use a primary model for shared investment structure and inherited settings. Set account-specific portfolio weights when a client needs additional sleeves, and customize implementation and settings for that account. This guide follows the **Chen Household IRA** and the **Global 80/20** model in the made-up Northwind Family Office practice.

## 1. Read the current account

Open **Clients**, find the client or household, and select the account. Open **Setup** to see its **Model**, **Portfolio**, **Sleeves**, and **Settings**. Check the account name above the tabs before editing.

To copy saved settings, open the **…** menu in the account header from any account tab and choose **Apply account template…**. Review the proposed changes and uncheck any you want to leave unchanged. See [Define and apply an account template](/advisor/account-templates/manage).

If the account needs a model, select **Assign model**, or **Change** beside an existing model. Choose the intended model, review the impact on account customizations, and select **Save**; Tilt saves the model at once. Apply or discard any queued setup changes before changing the model. When the account has its own portfolio weights, the new primary model replaces the previous model sleeve at its weight; additional sleeves keep their weights. Customizations under the previous model may stop applying. To assign a model to several accounts, use **Add accounts** on the model's **Accounts** view, as [Build a model portfolio](/advisor/build-model-portfolio#5-assign-the-model-to-accounts) describes.

**Portfolio** shows the account's top-level weights. Without account-specific weights, it shows 100% in the assigned model. **Sleeves** shows the effective tree beneath those weights. **Target %** is a sleeve's share of its parent, and **Account %** is its share of the account. **Source** shows whether a sleeve's tilts and direct indexing come from the model (**From model**) or from this account (**Account setting**). A collapsed composite counts the account changes inside it.

![Sleeves tree for the Chen Household IRA with Sleeve, Target %, Account %, and Source columns. US Large Growth (IUSG) shows Direct indexing and Account setting; the other rows show From model, and most rows have a Customize button.](https://mintcdn.com/tilt/CgV6P4zm-c-xhzLn/images/advisor/northwind-account-sleeve-tree.jpg?fit=max\&auto=format\&n=CgV6P4zm-c-xhzLn\&q=85\&s=aeebdf12496f7683ee036c2610ce56ef)

The Chen Household IRA follows Global 80/20's weights. It direct indexes US Large Growth inside US Large Cap; every other sleeve is set by the model.

### Check for off-model holdings

**Off model**, at the foot of **Sleeves**, lists the tickers the account holds that no sleeve or Tilt in **Sleeves** holds. Each ticker shows its share of the account, largest first. **None** means every holding counts in a sleeve. The section appears once the account has a model.

Check it when you set up an account that arrives with its own holdings, before its first optimization. Tilt values the holdings at the latest prices against the saved setup, so the list is ready before any optimization or drift check. Queued changes reach the list after you apply them.

![Foot of the Sleeves tree for the Chen Household IRA. Below the Core Bonds row, the Off model section reads Not in any sleeve and lists ARKK at 2.73% of the account with a Keep in a sleeve button.](https://mintcdn.com/tilt/A7in4o4fNuhYYQPm/images/advisor/northwind-account-off-model.jpg?fit=max\&auto=format\&n=A7in4o4fNuhYYQPm\&q=85\&s=dd19de8c886c69238617beb7713810ba)

The Chen Household IRA holds ARKK, which none of its sleeves holds.

Tilt sells off-model tickers over time, within the account's tax settings. For each ticker, choose where it counts while you still hold it:

* To count it in a sleeve, select **Keep in a sleeve…**, and **Legacy holdings** opens with the ticker chosen. Choose a sleeve and save the assignment; the ticker then counts in that sleeve and leaves the list. Tilt buys no more of it and still works toward selling it within the account's constraints. [Transition legacy holdings into a sleeve](/advisor/transition-legacy-holdings) covers the sell-down threshold and how the sale is reviewed.
* To leave it off model, do nothing. It stays on the list until Tilt sells it.

**Keep in a sleeve…** appears only when you can edit the account. In chat, ask **"Which holdings on the Chen Household IRA are off model?"** Tilt Agent runs the same check and answers in Setup's words. To see where any holding counts, select its **Weight** on the **Holdings** tab; see [where a holding counts](/advisor/monitoring-explained#see-where-a-holding-counts).

### Set account portfolio weights

To keep Global 80/20 as the primary model while adding a Gold sleeve for this account:

1. Apply or discard queued setup changes before editing the portfolio.
2. Under **Portfolio**, select **Edit portfolio**. The assigned model is marked **Primary model**.
3. Use **Add a sleeve** to choose the Gold sleeve from your organization.
4. Set Global 80/20 to 90% and Gold to 10%. The total must be 100%, and the primary model must keep a positive weight.
5. Select **Save portfolio**. This saves at once, outside **Queued changes**. **Cancel** leaves the saved portfolio unchanged.
6. Reopen the editor to check the saved weights. **Sleeves** now shows the account's model and additional sleeves with their effective settings.

The primary model still supplies inherited settings. Each sleeve keeps its shared investment definition, so changes to what it holds can reach this account. Saving these weights changes only this account's portfolio; it does not edit the model or the additional sleeve.

To remove the account-specific portfolio weights, select **Use inherited allocation** in the editor. This saves at once and returns the account to its inherited allocation, 100% in the assigned primary model. This control resets portfolio weights; sleeve customizations and other account settings are separate choices.

[Models, sleeves, and benchmarks](/advisor/models-and-benchmarks#accounts-can-combine-a-primary-model-and-other-sleeves) explains how the weights combine. To replace the primary model, use **Change** beside **Model** rather than trying to remove its row from the portfolio.

## 2. Customize a sleeve

Select **Customize** on a sleeve to set what it holds, its tilts, and its direct indexing for this account. Its weight comes from the saved portfolio and the shared sleeves within it. Use **Edit portfolio** to change this account's top-level weights.

A sleeve's place in the tree sets what you can customize:

| Sleeve | What you can set |
| - | - |
| One of the model's top-level sleeves | What it holds and its tilts, plus direct indexing for a building block. Tilts on a top-level composite reach every building block it holds; see [How a tilt changes a sleeve](/advisor/models-and-benchmarks#how-a-tilt-changes-a-sleeve). |
| A building block inside a composite | What it holds, its tilts, and direct indexing, at this place in the model only |
| A composite inside a composite | What it holds; customize the building blocks inside it for anything else |

A customization of a sleeve inside a composite applies at that place only. Direct indexing on a top-level sleeve also applies wherever the same sleeve appears inside a composite; to set one of those places differently, customize its row too. On a top-level composite, **Weights with these tilts** previews each holding's weight before and after the tilts, in every building block the composite holds. Select **Use the model's setting** or **Use the model's tilts** to remove the account's own value. When the account sets direct indexing for a sleeve itself, **Use the model's setting** at one of the sleeve's places inside a composite clears that setting, and every place that followed it goes back to the model. The dialog lists those other places before you queue the change. [Models and benchmarks](/advisor/models-and-benchmarks#accounts-customize-how-sleeves-are-managed) explains what happens to a customization when the model changes.

To inspect a composite's target weights without saving, edit its Tilts and select **Cancel** after reviewing **Weights with these tilts**. [Preview without saving](/advisor/models-and-benchmarks#preview-without-saving) explains the preview's scope and how to read its percentages.

### Change what a sleeve holds

An account can hold something other than the model's choice for any sleeve, while keeping the model's weight. In **Customize**, choose under **Holds**:

* **Another sleeve…** to hold one of your organization's sleeves.
* **Edit for this account…** to hold an ETF, index, Tilt, single security, or basket for this account only. This option appears on building blocks.
* **Model's holding** to go back to what the model holds.

Once the account holds another sleeve, its row in **Sleeves** shows that sleeve's name, what it holds, and the model sleeve it overrides, for example **US Large Cap Funds** with *Holds SPDR Portfolio S\&P 500 ETF · Overrides model sleeve: US Large Cap*. The account's drift check names the row the same way. An edit for this account keeps the model sleeve's name.

An account that holds another sleeve or its own edit in a sleeve's place drops the model's tilts there. Later changes the model makes to those tilts don't reach the account. Tilts on a composite above the sleeve apply as usual. To tilt the new holding, add the account's own tilts in **Customize**; choose **Model's holding** to bring the model's tilts back. In **Sleeves**, the info button on the sleeve's row lists the model's tilts that don't apply.

![US Mid Cap dialog. Holds lists Model's holding (VO), Another sleeve: US Mid Cap Core (selected), and Edit for this account, above a list of the firm's sleeves. A note reads: FSMDX is being sold down into VO here. After this change, sales go into US Mid Cap Core, and its sell-down plan needs a review in Legacy holdings.](https://mintcdn.com/tilt/F6YFsZbsydHw-1LM/images/advisor/cedar-account-holds.jpg?fit=max\&auto=format\&n=F6YFsZbsydHw-1LM\&q=85\&s=5e2c58feee2e4609ca665b0f3d38a3d5)

Avery Chen's account in the made-up Cedar Ridge Wealth practice will hold the firm's US Mid Cap Core sleeve in place of VO.

If the account is selling down a legacy position into that sleeve, the dialog warns you. After you apply the change, open **Legacy holdings** in **Settings** and review the sell-down plan.

When several accounts on a model use **Edit for this account…** to hold the same thing in the same sleeve, you can turn that edit into one sleeve for all of them; see [Save a shared edit as a sleeve](/advisor/compare-account-configurations#4-save-a-shared-edit-as-a-sleeve). Tilt Agent can also make these changes for you to review.

### When the model drops a customized sleeve

If the model stops holding a sleeve where this account changed the holding, or a sleeve inside a composite that this account customized, Setup keeps the customization and shows it as **Not in the model**. It applies again if the model adds the sleeve back. Select **Remove** to delete it.

![Sleeves tree for Jordan Patel's account. Under US SMID Cap Equity, US Mid Cap and US Small Value follow the model. US Small Cap shows a Not in the model badge, the text Holds US Small Cap (IJR) for this account. Applies again if the model puts US Small Cap back here, and a Remove button.](https://mintcdn.com/tilt/F6YFsZbsydHw-1LM/images/advisor/cedar-account-not-in-model.jpg?fit=max\&auto=format\&n=F6YFsZbsydHw-1LM\&q=85\&s=be02b4dc8ef8d124c6fc2a313c135201)

The model replaced US Small Cap with US Small Value. Jordan Patel's account keeps its US Small Cap customization for now.

## 3. Change account settings

Select a settings group: **Tax**, **Transactions**, **Optimization**, **Constraints**, or **Rules**. Each field in the group's dialog shows where its value comes from: the account, model, firm, or Tilt's defaults. In **Constraints** and **Rules**, inherited items are listed with where they come from. A field or list with a queued change is marked **Changed**, and a field also shows the value it had. [Set conditional rules and preview their effect](/advisor/configuration-and-rules) covers the **Rules** editor, conditional restrictions and bounds in **Constraints**, and the account's unsaved optimization preview.

![Account Settings listing Tax, Transactions, Optimization, Constraints, Rules, and Legacy holdings, each with a one-line summary of its values.](https://mintcdn.com/tilt/CgV6P4zm-c-xhzLn/images/advisor/account-settings.jpg?fit=max\&auto=format\&n=CgV6P4zm-c-xhzLn\&q=85\&s=099726ea449ec2aa68695e8ac03d60ff)

An account's Settings list includes Rules below Constraints, with a summary for each group.

In chat, ask for a concrete setting, such as **"Propose a 5% USD cash buffer for the Chen Household IRA. Show the current value, the value that would take effect, and its source. Do not save yet."**

Review the full proposal. The account can have restrictions, cash settings, tax preferences, direct-indexing choices, and Tilt adjustments. A change may replace a complete collection, so check which existing choices the proposal preserves. Confirm the specific account change only after the proposed and effective values match your intent.

To sell an existing equity or ETF over time, open **Setup → Settings → Legacy holdings**. Assign it to a sleeve so it counts there while you still own it. Saving is immediate and places no trades. [Follow the legacy-holdings example](/advisor/transition-legacy-holdings) to set a sale threshold and review opportunities.

## 4. Verify the result

For queued sleeve and settings edits, open **Queued changes** at the bottom of the page. Review each old and new value. Remove a change you do not want, choose **Discard all** to abandon the draft, or select **Apply** to save it. Apply or discard the queue before requesting an optimization.

Reopen **Edit portfolio**, the relevant sleeve, or a settings group to check its saved value and source. In chat, ask: **"Read the Chen Household IRA's saved setup and explain which values now take effect."** If Tilt reports a conflict or uncertain save, inspect the account again before proposing the remaining change.

Account tailoring changes optimization inputs and places no trades. Open **Optimization** and select **Optimize** to create a proposal from the saved portfolio and settings. Inspect the proposed holdings and trades before deciding whether to send orders. Saving a legacy assignment analyzes its transition; [Review a rebalance](/advisor/review-rebalance) covers the separate trading proposal. The account's model shows it in a configuration with any other accounts that customize the model's sleeves the same way; see [Compare a model's account configurations](/advisor/compare-account-configurations).


# Tax-aware portfolio management
Source: https://docs.tilt.now/advisor/tax-aware-management

Understand cost basis, tax lots, substitute securities, loss harvesting, and the assumptions behind proposed tax outcomes.

Tax-aware management considers the estimated tax consequences of trades alongside allocation, risk, costs, and restrictions. The Platform uses saved tax lots and the account's effective tax preferences to estimate the tax impact of proposed sales. A position's market value alone cannot tell you the gain or loss a sale would realize.

## Cost basis and tax lots

A tax lot records a quantity acquired with its cost basis and acquisition date. A position can contain several lots with different gains, losses, and holding periods. In the U.S., a capital gain or loss generally compares sale proceeds with adjusted basis; short-term and long-term treatment also depends on the holding period. See the [IRS explanation of capital gains and losses](https://www.irs.gov/taxtopics/tc409).

Consider this simplified individual-lot example for a U.S. account. One ticker trades at \$80, and each lot contains ten shares:

| Lot | Cost per share | Unrealized gain or loss | Result of selling five shares |
| - | - | - | - |
| Earlier purchase | \$50 | \$300 gain | \$150 gain |
| Later purchase | \$90 | \$100 loss | \$50 loss |

Both five-share sales produce \$400 of proceeds, but their gains and losses differ. This example excludes fees, foreign exchange, basis adjustments, and loss-disallowance rules. It illustrates why lot selection matters, rather than a tax benefit guaranteed by either sale.

## Jurisdiction and lot method change the calculation

Tilt's U.S. tax calculation supports several lot-selection methods, including first-in, first-out and last-in, first-out, as well as tax-aware selection. Its Canadian tax calculation uses average cost, consolidating the supplied lots for the same asset into a weighted average cost. Do not interpret the individual-lot example above as Canada's average-cost calculation.

Configured jurisdiction, tax rates, holding-period settings, and lot method affect the estimates. Check the effective account preferences rather than assuming an organization's defaults apply. For foreign-currency holdings, cost-basis currency and the relevant exchange-rate data also matter.

## Harvesting losses has an investment tradeoff

Tax-loss harvesting sells a position at a loss with the aim of obtaining a usable tax benefit. The proposal may replace the exposure with another permitted investment or retain some deviation from the target. Costs, restrictions, and modeled risk can make a loss sale unattractive even when an unrealized loss exists.

Tax emphasis changes the optimizer's preference among possible portfolios. A configured realized-gain target is distinct: Tilt can search across tax emphasis to approach that target within its configured tolerance. Inspect the achieved result; a preference or target alone is not a guarantee that every run reaches it. [How optimization makes tradeoffs](/advisor/optimization-explained) explains how these inputs interact.

A modeled benefit from losses also depends on assumptions about gains available to offset. Tilt's tax calculation assumes gains are available to offset when estimating a net loss benefit; the calculation does not establish that those gains exist for the client. A proposed loss amount and an immediately usable tax saving are different quantities.

## Substitute securities can preserve an existing allocation

Tilt supports configured substitution pairs: two securities that the optimizer can choose between while preserving their combined current portfolio weight. You can configure these pairs in account, model, or organization optimization settings. Check the account's effective settings to see which pairs apply.

For example, suppose you configure VTI and ITOT as a pair and an account holds 10% in VTI and none in ITOT. The optimizer keeps that combined 10% in one member of the pair. It can retain VTI or propose selling VTI and holding ITOT, depending on tax lots, costs, risk, and restrictions. A loss on VTI can make the switch attractive for tax-loss harvesting, but configuring the pair does not require the optimizer to harvest that loss.

The pair preserves the weight already held at the start of the optimization. It does not set a new target weight or require a purchase when neither security is held. A no-trade restriction or another constraint can prevent a switch; review the proposal to see which holding and trades Tilt selected.

### Substitution pairs and sleeve ETF alternatives serve different purposes

Sleeve ETF alternatives define permitted investments for implementing a sleeve's exposure. Tilt also accounts for those alternatives when attributing holdings to sleeves. A substitution pair constrains the combined weight of two existing holdings during optimization. Configure sleeve alternatives when you want an allowed ETF to count toward a sleeve; configure a substitution pair when you want to preserve an existing pair's combined allocation while allowing a switch. See [Models, sleeves, and benchmarks](/advisor/models-and-benchmarks#exposure-and-implementation-are-related-choices).

### A configured pair still needs a wash-sale assessment

VTI and ITOT illustrate the investment substitution mechanism. Configuring them as a pair does not establish that they avoid U.S. wash-sale rules. The IRS requires a facts-and-circumstances assessment of whether securities are substantially identical; a different ticker alone does not establish the tax treatment. See [IRS Publication 550](https://www.irs.gov/publications/p550).

Review the replacement security and the client's relevant purchases and sales before treating a proposed loss as deductible. The loss-disallowance checks described below use recorded asset identities and timing; substitution-pair settings do not define tax equivalence between securities.

## Loss-disallowance rules require broader context

U.S. wash-sale rules can disallow a loss when substantially identical securities are acquired within the applicable period around a loss sale. Canada's superficial-loss rules consider acquisitions of identical property by the taxpayer or an affiliated person and ownership at the end of the relevant period. See [IRS Publication 550](https://www.irs.gov/publications/p550) and the [CRA capital-gains guide](https://www.canada.ca/en/revenue-agency/services/forms-publications/publications/t4037/capital-gains.html).

Tilt incorporates recorded purchase and loss-sale timing from other saved accounts of the same client, or from accounts in the linked household. This aggregation uses matching asset identities and recorded dates. It does not establish that every substantially identical or identical investment, affiliated person, or external transaction has been identified. Configuring an ETF alternative is an investment implementation choice, not a tax-law determination that the replacement avoids loss disallowance.

The completeness of connected accounts, household relationships, tax-lot data, and transaction timing therefore affects the assessment. Planned or later purchases can also change the outcome after a proposal is created.

## Allow a wash sale on purpose

By default, Tilt keeps a proposal from buying a ticker back within the **Wash-sale window** after the account sold it at a loss. Sometimes you want that trade anyway, for example when the client values getting back into the position more than keeping the loss. Override the prevention for an account, either for chosen tickers or for the whole account:

1. Open the account's **Setup** tab and click the **Tax** row under **Settings**.
2. To allow wash sales for specific tickers, search for each one under **Wash-sale override tickers**.
3. To allow them for the whole account, set **Wash-sale policy** to **Allow wash sales**.
4. Queue and apply the change.
5. On the **Optimization** tab, click **Optimize** to generate a new proposal, then review it before you approve trades.

![Tax dialog with Wash-sale policy set to Follow prevention rules, and under Wash-sale override tickers, VIU listed with a remove button above the Search ticker field, a Clear ticker overrides link, and an Account setting label.](https://mintcdn.com/tilt/CgV6P4zm-c-xhzLn/images/advisor/wash-sale-override.jpg?fit=max\&auto=format\&n=CgV6P4zm-c-xhzLn\&q=85\&s=ae2815acb95d2f89ace07b5efe0ae91a)

The Tax dialog for Wei Chen's Chen Household IRA in Northwind Family Office, with VIU added as a wash-sale override ticker before the change is queued.

The override applies to proposals generated after you apply it. It lifts the wash-sale blocks; no-hold and no-trade restrictions still apply.

Overrides stay in place until you clear them. To restore prevention, click **Clear ticker overrides**, set **Wash-sale policy** back to **Follow prevention rules**, or both. Then apply the change and generate a new proposal.

The **Tax** row on a model's or the firm's **Setup** has the same fields. Accounts inherit them unless they set their own.

## Read estimated outcomes in context

A proposal's tax report describes estimated consequences of proposed trades under the run's data and assumptions. It is not a completed tax return or evidence that trades have executed. Review realized gains and losses, lot method, rates, replacement exposure, and any data warnings together.

For an existing appreciated portfolio, reducing drift may realize gains. Preserving appreciated holdings may defer those gains while retaining risk relative to the target. Compare the tax estimate with the allocation and risk outcome before accepting either approach.

## Legacy sell-downs use available annual gains capacity

A [legacy holding](/advisor/transition-legacy-holdings) is an investment you plan to sell over time. Tilt will not buy more. Two settings answer different questions:

| Setting | Meaning |
| - | - |
| **Sell-down alert threshold** | How much of the holding must a proposal sell to create a review opportunity? |
| Annual capital-gains budget | How much net gain is allowed for the year? The remaining amount limits each proposal. |

For example, a **\$5,000 annual budget** with **\$4,700 in recorded net gains** leaves **\$300**. In a taxable account with an active legacy assignment, that remainder caps the proposal's total net gains. A sale with a \$400 gain needs at least \$100 in offsetting losses to fit, even if it meets the sale threshold. Fitting the budget does not guarantee Tilt will propose the sale; other constraints still apply.

Tilt uses the client's budget when set, otherwise the household's. Recorded short- and long-term gains and losses count toward the current New York calendar year. When the budget is used up, the net-gains ceiling is zero; losses can still offset gains. If gains records are incomplete for any counted account, confirm them before optimizing. Without an annual budget, other account tax settings still apply.

> [!WARNING]
>
> The remaining budget is not reserved. If two account proposals each use the same \$300 remainder, together they could exceed it. Check their combined gains before approving trades.

[Reports and backtests](/advisor/reports-and-backtests) explains the available evidence. [Review a rebalance](/advisor/review-rebalance) covers the separate proposal and execution review.

***

Wash-sale rules may disallow a loss if substantially identical securities are bought within 30 days before or after the sale, including in the client’s other accounts, such as IRAs or a spouse’s accounts. The Platform’s wash-sale checks cover only accounts on the Platform, so confirm the client’s full position with a qualified tax professional.

Tilt provides portfolio technology, not investment, tax or legal advice, and is not a registered investment adviser or broker-dealer. The advisor makes all investment decisions, including whether to accept a proposal and submit trades, directly or through approval rules the advisor configures. Trades are executed through the client’s custodian. Estimates depend on the data and assumptions recorded for the account; confirm the client’s tax treatment with a qualified tax professional.


# Trade release conditions
Source: https://docs.tilt.now/advisor/trade-release-conditions

Definitions, threshold boundaries, and evidence limitations for organization trade release rules.

Organization owners can combine these conditions in [trade release rules](/advisor/trade-release-rules). A matching rule flags the whole account proposal. Reviewers inspect the results in [Trading > To review](/advisor/review-rebalance#review-the-morning-trading-queue).

| Condition | Measurement |
| - | - |
| All trades | Any nonempty optimizer security-trade proposal. |
| Absolute dollars | Absolute proposed security-trade value in USD. Tilt combines rows for the same security and direction, without adding unrelated buys and sells into proposal turnover. |
| Percentage of account value | Security-trade USD value divided by authoritative account net value, including cash. Missing or unusable value is unknown; Tilt does not substitute invested-only assets. Current coverage requires fresh positive broker-reported net value for a USD account. |
| Percentage of security ADV | Security-trade dollar value divided by six-month average daily dollar volume (ADV), excluding the current partial day. This measures one security trade, not book-wide participation or live execution. |
| Wash sales | Potential conflicts from known account and household tax lots and the proposal itself. Tilt compares identical securities, including known acquisitions or loss dates within the preceding 30 days and buys against proposed loss sales. Outside accounts, future activity, and incomplete acquisition or realized-loss histories limit coverage. This is not definitive tax clearance. |
| Recent deposits | Identifiable inbound cash contributions and cash transfers within the selected lookback, using posted/effective activity dates rather than import time. Excludes sale proceeds, dividends, currency conversions, and in-kind transfers. |
| Account status changes | Observed transitions between known normalized account statuses within the selected lookback. Current status alone does not establish a change. |
| Failed trades/proposals | Optimizer failures and actual order failures or rejections within the selected lookback. Excludes ordinary market-closed waits, policy blocks, and cancellations. |
| Portfolio changes | Saved settings changes to the account, its model, any sleeve it holds, or the firm within the selected lookback. Names, notes, and monitoring thresholds don't count, and neither do price movement or routine fills. Only changes saved through Tilt's settings are recorded, so finding none is treated as unknown. |

## Thresholds and lookbacks

For dollar and percentage conditions, choose **greater than** or **greater than or equal to** and a nonnegative threshold. At a \$100,000 threshold, a \$100,000 trade matches only the inclusive comparison. A 5% threshold compares the trade with 5% of account value or security ADV, as applicable.

Recent deposits, account status changes, failed trades/proposals, and portfolio changes require a lookback in positive whole days. Tilt evaluates the window from the evaluation time minus that number of days through the evaluation time, including both boundaries.

## Evidence coverage

Tilt uses persisted proposal, brokerage, tax-lot, and configuration evidence. Missing trade USD valuations, account values, or positive volume history can prevent a numeric evaluation.

| Rule result | Effect on sending |
| - | - |
| Matched | The sender must be eligible under this rule. |
| Could not evaluate | The sender must be eligible under this unresolved rule and inspect its missing evidence. |
| Not matched | This rule adds no sender restriction. A known-false condition settles an AND rule as not matched even if another condition lacks evidence. |

The absence of a recorded deposit, failure, or wash-sale conflict does not establish complete history. These conditions can remain **Could not evaluate** when Tilt finds no event. Status and portfolio-change checks also need a history baseline covering the start of the lookback to establish that no change occurred. Inspect each result's evidence and missing-coverage reason before sending.

Annual capital gains is not an available condition. Projected gains in a proposal do not establish calendar-year realized gains.


# Configure trade release rules
Source: https://docs.tilt.now/advisor/trade-release-rules

Flag optimizer proposals for review and choose who can send them for your organization.

Organization owners configure trade release rules to flag optimizer-generated account proposals and restrict who can send them. A proposal belongs to the account and organization; the person who requests optimization does not determine release authority.

## 1. Add a rule as an organization owner

Open **Firm**, then **Setup** > **Trade release rules**. Only organization owners can edit these rules.

Select **Add rule**. Under **When**, choose a condition, set any threshold or lookback, and use **Add AND condition** to combine conditions. Tilt uses the conditions as the title unless you expand **Optional label** and enter a **Custom label**. See the [condition reference](/advisor/trade-release-conditions) for measurements and coverage.

All conditions within a rule must match. If you combine security-trade conditions, the same security and direction must satisfy them. Account conditions can combine with that qualifying trade.

For example, a rule for a trade over \$100,000 AND over 5% of its security's average daily dollar volume does not match when one ticker meets only the dollar threshold and another meets only the volume threshold.

## 2. Choose who can send flagged proposals

Under **Who can send**, select at least one current member per rule. Selected members still need trading permission. Owners cannot bypass a rule.

For overlapping rules, one person must have trading permission and appear in the eligible-member list of every matched or unresolved rule. Separate people's permissions do not combine. If no current member satisfies all requirements, an organization owner must repair the rules or member permissions before anyone can send.

For example, Tyler can review the whole morning queue while the firm uses flags to prioritize his attention. Later, a junior colleague with trading permission can send ordinary proposals. To reserve flagged proposals for Tyler, select Tyler as the eligible member on the relevant rules. Tyler reviews and sends those proposals himself; the junior colleague does not receive an approval to execute later.

## 3. Queue the rule and apply firm changes

Check **Active**, conditions, and eligible members, then select **Add to policy**. For an existing rule, select **Update rule** after editing or **Remove rule** to queue its removal.

Review **Queued changes**, including any other firm edits, then select **Apply firm changes**. Check overlapping rules together so the intended sender remains eligible. Tilt records who changed the rules and the before-and-after configuration.

Successful saves leave the shared queue; failed changes remain for review. See [Review the firm](/advisor/review-the-firm#setup) for queue controls.

You can also ask Tilt Agent for a [change review](/tilt-agent/change-reviews) before saving:

> Show me a Change Review for our firm's trade release rules. Add a rule named Large trades for security trades greater than \$100,000, with Tyler as the eligible sender. Preserve the other rules. Show the complete policy before and after, and do not apply it yet.

Ask for the review explicitly. Check that it covers the right firm and shows the complete policy, including unchanged rules, conditions, and eligible members. **Apply** replaces the firm's complete release policy and requires an organization owner. If someone changed the saved policy after preparation, request a fresh review.

Saving a policy does not send trades. Follow [Review a rebalance](/advisor/review-rebalance#review-the-morning-trading-queue) to inspect flags and make a separate send decision.

## Scope

Trade release rules cover optimizer-generated account proposals. Optimizer restrictions, trading restrictions, and execution permissions still apply. These rules do not flag manual trades or monitor live execution.


# Transition legacy holdings into a sleeve
Source: https://docs.tilt.now/advisor/transition-legacy-holdings

Assign legacy holdings to a sleeve, understand their contribution to tracking error, and review sell-down opportunities within tax constraints.

Use **Legacy holdings** for an equity or ETF you want to sell over time. Assign it to a sleeve so Tilt counts it there while you still own it. Tilt will not buy more.

When you first save the assignment, Tilt records the number of shares you hold as the **accepted quantity**. This is the share balance your transition plan allows you to retain. Tilt reduces it as recorded sales occur.

The assignment connects monitoring, optimization, and sale review:

| Stage | How Tilt treats the legacy holding |
| - | - |
| Monitoring | Includes its current value in the assigned sleeve for allocation drift and tracking error. The transition reference includes the accepted quantity you plan to retain. |
| Optimization | Uses the destination benchmark, with zero weight in the legacy holding, to work toward selling it down within the account's constraints. |
| Sell-down opportunity | Prompts advisor review when the final sale meets the sell-down alert threshold and fits the applicable tax constraints, including remaining annual gains capacity when a budget applies. |

For example, an account owns **100 shares of an older ETF**. You want that investment to count toward **US Large Cap** while moving into the sleeve's intended holdings. The older ETF has no place in that final portfolio: its destination weight is zero.

## 1. Assign the holding in Setup

Open **Clients**, choose the client and account, then go to **Setup → Settings → Legacy holdings**. Select **Add legacy holding**.

1. Under **Holding**, choose the older ETF.
2. Under **Sleeve**, choose **US Large Cap**, or the appropriate building block inside it. Choose the full path you intend if a sleeve appears more than once.
3. Set **Sell-down alert threshold** to **10%**.
4. Select **Save assignment**.

You can also start from a ticker the model doesn't hold. In **Setup**, select **Keep in a sleeve…** beside it under **Off model**, and the form opens with the ticker under **Holding**. See [Check for off-model holdings](/advisor/tailor-account#check-for-off-model-holdings).

With 100 shares remaining, a 10% threshold means a proposal must sell at least **10 shares** to create a legacy sell-down opportunity for review. You can instead set a minimum USD sale value. Zero means any positive sale.

Saving takes effect immediately, outside **Queued changes**, and places no trades. The threshold decides when to show an opportunity; it does not set a tax budget or require a sale.

On the account's **Holdings** tab, the holding's **Weight** then shows its assigned sleeve with a **Legacy** label. See [where a holding counts](/advisor/monitoring-explained#see-where-a-holding-counts).

Tilt checks eligibility before saving. Use a positive-weight building block, not a composite, and a ticker with zero destination weight across the benchmark and tilts. Cash and manual assets are excluded. Resolve any reported tax-lot, price, foreign-exchange, or risk-coverage gaps before trying again.

## 2. Understand how legacy holdings contribute to tracking error

Run monitoring after saving the assignment, then open **Tracking error details** in **Legacy holdings** to see both measures and their measurement dates. Saving an assignment does not calculate these results. If the details show **Current tracking error is unavailable**, run monitoring and reopen the details before checking for input or assignment problems.

### The holding counts toward its assigned sleeve

An assigned legacy holding contributes its current market value to the chosen sleeve and its parent sleeves. The assignment preserves the model's target allocation.

The **model-drift basis** is the account value Tilt uses to calculate allocation weights: eligible holdings plus cash above the account's reserve. It excludes manual assets, the separately recorded non-tradable asset balance, and the cash reserve.

Continue with an account that has a **\$100,000 model-drift basis**, with a **50% US Large Cap target**. It holds **100 shares of an older ETF at \$100 per share** and **\$40,000 of replacement holdings** in US Large Cap.

| Calculation | Result |
| - | - |
| Legacy ETF value: 100 × \$100 | \$10,000 |
| Current sleeve value: \$10,000 + \$40,000 | \$50,000 |
| Current sleeve weight: \$50,000 ÷ \$100,000 | 50% of the account's drift basis |
| Legacy ETF weight within the sleeve: \$10,000 ÷ \$50,000 | 20% |

The sleeve matches its 50% allocation target, even though one fifth of its value remains in the older ETF. Allocation drift and tracking error answer different questions.

An assigned legacy ticker with a price and tax lots counts toward its sleeve. [Monitoring explained](/advisor/monitoring-explained#model-allocation-drift-measures-changes-in-allocation) describes the exclusions and cash treatment.

### Transition and destination tracking error use different references

Both measures compare current holdings, normalized within the sleeve, with reference weights. They differ in the reference portfolio:

| Measure | Reference | What it tells you |
| - | - | - |
| **Transition tracking error** | The accepted legacy quantity, valued at current prices, plus replacement holdings for the rest of the sleeve. | How closely current holdings follow the transition plan. |
| **Destination tracking error** | The resolved destination portfolio, with zero weight in the legacy ticker. | The remaining estimated return variability relative to the destination. |

### Tilt values the accepted quantity at current prices

The **replacement mix** specifies how to divide the sleeve's value after allowing for the legacy holding. Tilt saves this mix with the accepted quantity. It values the accepted shares at current prices and allocates the rest of the sleeve to replacements.

In the example, the accepted **100 shares** are worth **\$10,000**, or **20%** of the **\$50,000 sleeve**. Replacements take the remaining **80%**. With an unchanged destination, Tilt uses the saved mix. When the destination changes and the assignment remains compatible, Tilt uses the current destination mix while retaining the accepted legacy quantity.

> [accordion] Reference-weight calculation
>
> ```text theme={null}
> Legacy reference weight = accepted shares × current USD price ÷ current sleeve value
> Replacement weight = (1 − sum of legacy reference weights) × replacement mix weight
> ```
>
> The formula returns weights as fractions: 100 shares × \$100 ÷ \$50,000 = 0.20, or 20%.
>
> Tilt retains the accepted quantity between recorded sales. For example, with the sleeve still worth \$50,000 and the ETF still at \$100, an unexpected purchase that raises actual holdings to **120 shares** creates a **24%** sleeve weight against the accepted **20%**. Monitoring measures that difference.

### How Tilt estimates tracking error

Active weight is current sleeve weight minus reference weight. Tilt uses a factor risk model to estimate how those differences affect return variability. It combines common factor exposures, factor covariance, and holding-specific risk. **Covariance** describes how returns move together.

When the factor model has insufficient coverage, Tilt falls back to historical returns covariance, which estimates those risk relationships from daily returns. Tilt applies this estimator choice to both transition and destination tracking error. If the required return history is also unavailable, the affected measurement remains unavailable.

For a simplified version of the example, treat the replacement holdings as one investment. Assume the legacy ETF and replacement investment each have **20% annualized volatility**, with **0.80 correlation**. These are illustrative assumptions.

| Holding | Current weight | Transition reference | Destination reference |
| - | - | - | - |
| Legacy ETF | 20% | 20% | 0% |
| Replacement investment | 80% | 80% | 100% |

The legacy ETF contributes **+20 percentage points of active weight** against the destination. Holding it leaves the replacement investment **20 percentage points underweight**. Tilt measures the risk of both differences together. Transition active weights are zero, so transition tracking error is **0%**. Destination tracking error includes the retained legacy exposure and is approximately **2.53% per year** under these assumptions.

> [accordion] Tracking-error calculation
>
> ```text theme={null}
> Tracking error = square root of (active weightsᵀ × annualized covariance × active weights)
> ```
>
> Weights enter the calculation as fractions. Multiply the result by 100 to express it as a percentage. In this two-investment example:
>
> ```text theme={null}
> Destination tracking error
>   = √(0.20² × 0.20² + (−0.20)² × 0.20²
>       + 2 × 0.20 × (−0.20) × 0.80 × 0.20 × 0.20)
>   ≈ 2.53% per year
> ```

A **20% legacy weight** therefore does not imply **20% tracking error**. The risk relationships matter: legacy exposure can add more or less tracking error depending on how it moves relative to the replacement holdings. Tracking error is not the sum of the weight differences. Tracking error estimates return variability relative to the reference; it does not predict a loss or a maximum return gap.

### Monitoring checks the transition measure against policy limits

For a sleeve undergoing a valid legacy transition, monitoring applies the tracking-error policy's warning and breach limits to **transition tracking error**. It also calculates destination tracking error, which remains visible under **Setup → Settings → Legacy holdings → Tracking error details**.

In the example, transition tracking error is **0%** and destination tracking error is approximately **2.53%**. An illustrative **2% breach limit** would pass the transition check. The destination figure still shows the remaining risk relative to the final portfolio.

The warning check triggers at or above its limit; the breach check triggers strictly above its limit. A proposal's sleeve risk calculation uses its proposed holdings against the destination. Compare the reference, holdings, measurement date, and risk snapshot before comparing a proposal with monitoring.

## 3. Review a sale when it is feasible

Optimization uses the destination benchmark, with **zero weight in the legacy holding**. The accepted quantity belongs to the monitoring reference; it does not become the optimizer's target. Tilt prevents additional purchases and works toward selling the position within tax and investment constraints.

A legacy sell-down opportunity requires both a large enough final sale and enough capacity under the applicable tax constraints. When an annual gains budget applies to a taxable account, Tilt caps the proposal's total net gains at the remaining capacity. Meeting the sale threshold alone is insufficient.

**Sell-down alert threshold** controls when a finalized proposal creates a legacy sell-down opportunity for review. It is separate from the tracking-error policy limits and the annual capital-gains budget.

```text theme={null}
Sale percentage = final proposed sale quantity ÷ existing holding quantity × 100
USD sale value = final proposed sale quantity × USD sale price
```

Tilt uses the final sale after trade sizing and lot selection. A sale qualifies when it is positive and meets or exceeds the chosen percentage or USD threshold. A zero threshold permits any positive sale.

With **100 shares remaining**, a **10% threshold** requires a sale of at least **10 shares**. After a recorded sale leaves **90 shares**, the same threshold requires at least **9 shares**. The percentage uses the remaining position, rather than the original assignment quantity.

Changing only the sell-down threshold on a valid assignment preserves its accepted transition reference. A qualifying sale can create a review opportunity without a drift breach. Other review reasons can apply even when the sale falls below this threshold.

### Gains capacity can limit a qualifying sale

Estimated gain adds up the quantity sold from each selected lot multiplied by its USD sale price minus its per-share cost basis.

Continue with the older ETF at **\$100 per share** and assume every share sold has a **\$60 cost basis**. Fees and other adjustments are excluded from this illustration.

| Proposed sale | Sale value | Estimated gain | Meets a 10% threshold on 100 shares? |
| - | - | - | - |
| 10 shares | \$1,000 | 10 × (\$100 − \$60) = \$400 | Yes |
| 5 shares | \$500 | 5 × (\$100 − \$60) = \$200 | No |

If the applicable annual gains budget is **\$5,000** and recorded net gains are **\$4,700**, the remaining capacity is **\$300**. With no other proposed gains or offsetting losses, the 10-share sale exceeds that capacity. The 5-share sale fits but misses the sell-down threshold. Neither creates a legacy sell-down opportunity in this example.

The budget constrains the proposal's total net gains. Offsetting losses and other gains can change the result. [Tax-aware management](/advisor/tax-aware-management#legacy-sell-downs-use-available-annual-gains-capacity) explains inheritance, gains records, and shared capacity across proposals.

Check the sale, replacement holdings, and tax estimate before approving trades. [Review a rebalance](/advisor/review-rebalance) covers approval and execution.

## 4. Check the transition after recorded sales

Tilt reduces the accepted legacy quantity from recorded sales. Generating, approving, or submitting a proposal alone does not advance the accepted reference. A proposed replacement mix takes effect after Tilt reconciles execution evidence with holdings.

After a recorded sale of 10 shares, the example's accepted legacy quantity becomes **90 shares**. If the price remains \$100 and the sleeve remains worth \$50,000, the legacy transition reference becomes **18%**, with **82%** in replacements. Actual holdings that match that reference still have zero transition tracking error; destination tracking error continues to reflect the remaining legacy exposure.

Check the measurement and risk-snapshot dates beside both results. If no measurements appear, run monitoring and reopen **Tracking error details**. If results remain unavailable, check for missing prices, incomplete risk coverage, or an incompatible assignment. An unavailable result does not establish zero risk. If the assignment shows **Needs review**, review and save it again before relying on its monitoring results.

To change the sleeve or threshold, use **Edit**. **Remove assignment** ends the legacy treatment; it does not sell the position.


# Article Portfolio Relevance
Source: https://docs.tilt.now/api-reference/backchannel/article-portfolio-relevance

POST /api/v1/backchannel/risk/article_portfolio_relevance
Classifies each article once and returns a comparable portfolio relevance score without generating a scenario tree.

Use this endpoint to rank a news feed for a portfolio without generating a scenario tree. Send up to 100 articles per request and compare `relevance_score` values within the response.

Each article may contain up to 50,000 content characters, with a maximum of 2,000,000 content characters across the request. Supplied `article_id` values must be unique within the batch.

The default `response_detail` is `score`. Use `explain` when you also need the classification reason and leading portfolio contributors. Use `full` only for debugging or deeper analysis.

Article classification is cached independently of the portfolio. Reusing the same headline, content, and publication time across portfolios avoids repeating the classification work, while each portfolio still receives its own relevance score.


# Get Company News
Source: https://docs.tilt.now/api-reference/backchannel/get-company-news

POST /api/v1/backchannel/news/companies

# Get Macro Sensitivities
Source: https://docs.tilt.now/api-reference/backchannel/get-macro-sensitivities

POST /api/v1/backchannel/risk/sensitivities

# Get Article Scenario
Source: https://docs.tilt.now/api-reference/backchannel/get-scenario

POST /api/v1/backchannel/scenarios/{id}

# Portfolio Feed
Source: https://docs.tilt.now/api-reference/backchannel/portfolio-feed

POST /api/v1/backchannel/scenarios/feed
One call: a portfolio, optional interests and a time window in; the window's Dow Jones articles out, grouped into titled stories (and optionally broader topics), ranked by importance lifted by how much each story is about this portfolio (an article tagged to a position, or one whose scenario tree moves the portfolio more than it usually moves against the market), spread so one topic does not take the whole page, each article carrying its portfolio exposure. Stories and titles are precomputed at ingest, so a call takes tens of milliseconds.

# Run Macro Scenario
Source: https://docs.tilt.now/api-reference/backchannel/run-macro-scenario

POST /api/v1/backchannel/risk/scenario

# Scenario Portfolio Analysis
Source: https://docs.tilt.now/api-reference/backchannel/scenario-portfolio-analysis

POST /api/v1/backchannel/risk/scenario_portfolio_analysis

# Search Companies
Source: https://docs.tilt.now/api-reference/backchannel/search-companies

POST /api/v1/backchannel/companies/search

# Search Dow Jones Archive
Source: https://docs.tilt.now/api-reference/backchannel/search-dow-jones-archive

POST /api/v1/backchannel/dow-jones-archive/search

# Search Scenarios
Source: https://docs.tilt.now/api-reference/backchannel/search-scenarios

POST /api/v1/backchannel/scenarios/search

# Delete Asset Class
Source: https://docs.tilt.now/api-reference/endpoint/delete-asset-class

DELETE /api/v1/custom/org/{organization_uuid}/asset_classes/{asset_class_uuid}/
Delete asset class

# Delete Client
Source: https://docs.tilt.now/api-reference/endpoint/delete-client

POST /api/v1/custom/org/{organization_uuid}/clients/{uuid}/delete/
Soft delete a client from the organization

# Delete Portfolio Config
Source: https://docs.tilt.now/api-reference/endpoint/delete-portfolio-config

DELETE /api/v1/custom/org/{organization_uuid}/portfolio_configs/{config_uuid}/
Delete a portfolio config for the organization

# Get Account Backtest Result
Source: https://docs.tilt.now/api-reference/endpoint/get-account-backtest-result

GET /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/backtests/{job_id}/

# Get Asset Class
Source: https://docs.tilt.now/api-reference/endpoint/get-asset-class

GET /api/v1/custom/org/{organization_uuid}/asset_classes/{asset_class_uuid}/
Retrieve asset class details

# Get Asset Classes
Source: https://docs.tilt.now/api-reference/endpoint/get-asset-classes

GET /api/v1/custom/org/{organization_uuid}/asset_classes/
List asset classes in the organization

# Get Benchmark Index
Source: https://docs.tilt.now/api-reference/endpoint/get-benchmark-index

GET /api/v1/custom/benchmark_indexes/{benchmark_identifier}/

# Get Benchmark Indexes
Source: https://docs.tilt.now/api-reference/endpoint/get-benchmark-indexes

GET /api/v1/custom/benchmark_indexes/
List the available benchmark indices that can be used as reference
for creating custom indices.

Supports typeahead search using the 'search' query parameter.

# Get Optimization Task Status
Source: https://docs.tilt.now/api-reference/endpoint/get-bulk-optimization-status

POST /api/v1/custom/org/{organization_uuid}/optimized_proposals/status/

# Get Client
Source: https://docs.tilt.now/api-reference/endpoint/get-client-details

GET /api/v1/custom/org/{organization_uuid}/clients/{uuid}/
View for retrieving and updating organization clients.

Supports:
- GET: Retrieve client details
- PATCH: Update the client's external ID and metadata. Holdings and
  account settings still update a client with exactly one account; a
  client with more updates each account at its own endpoint.

# Get Preview Job Result
Source: https://docs.tilt.now/api-reference/endpoint/get-dynamic-rules-preview-job

GET /api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/{job_id}/

# Get Dynamic Rules Schema
Source: https://docs.tilt.now/api-reference/endpoint/get-dynamic-rules-schema

GET /api/v1/custom/org/{organization_uuid}/dynamic_rules/schema/

# Get Index Constituents
Source: https://docs.tilt.now/api-reference/endpoint/get-index-constituents

GET /api/v1/indexes/{index_id}/constituents
Index constituents for a date. With no `date`, uses the most recent published level (the latest level date). A date with no published level returns 404; a level present but with no constituent snapshot returns 200 with an empty `data` array.

## Description

Retrieves the constituents for a specific index.

## Parameters

### Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `index_id` | Yes | The unique identifier of the index |

### Query Parameters

| Parameter | Required | Description |
| - | - | - |
| `date` | No | Effective date in `YYYY-MM-DD` format. Defaults to the most recent available date. |

### Default Behavior

* If `date` is not provided, returns constituents for the most recent available date


# Get Index Corporate Actions
Source: https://docs.tilt.now/api-reference/endpoint/get-index-corporate-actions

GET /api/v1/indexes/{index_id}/corporate-actions
Corporate actions affecting the index on the given date.

The feed includes every CA the index applied — dividends, special dividends, splits, stock distributions, bonus issues, removals (delisting/bankruptcy/M&A), spin-offs, and exchange changes.

With no `date`, returns the most recent date that has corporate actions for this index (an event feed, so this differs from /levels and /constituents, which default to the latest level date). Because dividends are included, the default date typically lands on a recent dividend/distribution date rather than the last structural event. When the index has no corporate actions for the requested or defaulted date, returns 200 with an empty `data` array and `effective_date: null` (not 404).

Each Primary row describes one CA. Any CA can carry Redistribution rows describing per-ticker share changes attributed to it. Removal CAs (delisting, bankruptcy, M&A, sanction removal, and an exchange change that moves the ticker off a home-exchange-restricted index's eligible exchange) carry rows whenever value was reassigned. A removal is not guaranteed to have at least one row; an empty `redistribution_rows` array can mean either the CA produced no share change or no recorded attribution exists for it yet (see below).

**Redistribution rows — content and reconciliation:**
Redistribution rows are recorded by the index at the time it applied the corporate action and describe the action's isolated, as-applied effect (the acquirer's legs, any replacement constituent it forced, and the level-preserving rescale) — not a re-derivation. An empty `redistribution_rows` array means either the CA produced no share change (the typical case for vanilla dividends, identifier-rotation exchange changes, and other no-op CAs) or no recorded attribution exists for that CA; the two cases are not separately signaled. When two or more removals share a single rescale on the same proposal, that shared rescale is recorded identically on each contributing removal's redistribution rows — both jointly caused it. Do not sum `redistribution_shares` across CAs on the same proposal; each row set independently describes the joint effect. Implicit signals are `old_index_shares=null` for a newly-added constituent and a negative `redistribution_shares` for a survivor whose shares were scaled down.

**Spin-offs:** the deal terms are reported via the `spin_off` sub-object. By default (`spin_off_eligible=true`) the spun-off company is ADDED as a new constituent, the parent is retained, and the new name is re-evaluated against the index rules at the next reconstitution; the addition appears as a Redistribution row when recorded (`old_index_shares=null`, `new_index_shares` equal to the spun-off shares). When `spin_off_eligible=false` the spun-off company is dropped and its value redistributed pro-rata (delisting-style) on the settlement date; that share change is reflected in the settlement date's constituent shares, not as Redistribution rows attached to this spin-off row.

**As-applied event values:** the event-input values on each Primary row and its sub-object (cash_per_share, exchange_ratio, deal_type, dist_pct, price adjustment factor, etc.) are frozen as of when the index applied the action, so a later edit to a still-pending corporate action does not change them. Security identity — the ticker the action targets and any acquirer/spun-off ticker — instead reflects the current corporate-action record, not the as-applied snapshot.

## Description

Retrieves corporate actions for a specific index.

## Parameters

### Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `index_id` | Yes | The unique identifier of the index |

### Query Parameters

| Parameter | Required | Description |
| - | - | - |
| `date` | No | Effective date in `YYYY-MM-DD` format. Defaults to the most recent date with corporate actions. |

### Default Behavior

* If `date` is not provided, returns corporate actions for the most recent date with corporate actions


# Get Index
Source: https://docs.tilt.now/api-reference/endpoint/get-index-details

GET /api/v1/indexes/{index_id}
Retrieve an index by UUID.

# Get Index Levels
Source: https://docs.tilt.now/api-reference/endpoint/get-index-levels

GET /api/v1/indexes/{index_id}/levels
Index level for a date. With no `date`, returns the most recent published level (the latest level date). A date with no published level returns 404..

## Description

Retrieves the levels for a specific index.

## Parameters

### Path Parameters

| Parameter | Required | Description |
| - | - | - |
| `index_id` | Yes | The unique identifier of the index |

### Query Parameters

| Parameter | Required | Description |
| - | - | - |
| `date` | No | Effective date in `YYYY-MM-DD` format. Defaults to the most recent available date. |

### Default Behavior

* If `date` is not provided, returns levels for the most recent available date


# List Index Levels History
Source: https://docs.tilt.now/api-reference/endpoint/get-index-levels-history

GET /api/v1/indexes/{index_id}/levels/history
Returns historical index levels, optionally filtered by date.

# List Index Notifications
Source: https://docs.tilt.now/api-reference/endpoint/get-index-notifications

GET /api/v1/indexes/notifications
Paginated list of published index governance notifications, ordered by effective date (most recent first, undated last). Each notification includes a link to its page on the Tilt website. Supports filtering by effective date range, announcement type, affected index, and (via subscribed=true) the indexes your API key is entitled to.

# Get Optimization Task Result
Source: https://docs.tilt.now/api-reference/endpoint/get-optimization-task-result

GET /api/v1/custom/org/{organization_uuid}/optimized_proposals/{proposal_uuid}/

# Get Clients
Source: https://docs.tilt.now/api-reference/endpoint/get-org-client

GET /api/v1/custom/org/{organization_uuid}/clients/
List clients in the organization. Supports optional search across external_id and metadata fields, and ordering by created date.

# Get Organization
Source: https://docs.tilt.now/api-reference/endpoint/get-org-details

GET /api/v1/custom/org/{organization_uuid}/

# Get Aggregate Holdings
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-holdings

GET /api/v1/custom/org/{organization_uuid}/reports/holdings/
Get an aggregated report for the holdings across all clients.

# Get Aggregate Holdings by Constituents
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-holdings-constituents

GET /api/v1/custom/org/{organization_uuid}/reports/holdings/constituents/
Get an aggregated report for the holdings across all clients, grouped by constituent. The results are sorted by descending total market value.

# Get Optimization Metrics
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-optimizations

GET /api/v1/custom/org/{organization_uuid}/reports/optimizations/
Get metrics for the portfolio optimizations which have been run.

# Get Aggregate Trade Proposals
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-proposals

GET /api/v1/custom/org/{organization_uuid}/reports/proposals/
Get an aggregated report for trade proposals which have been generated.

# Get Aggregate Proposals by Constituent
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-proposals-constituents

GET /api/v1/custom/org/{organization_uuid}/reports/proposals/constituents/
Get an aggregated report for trade proposals which have been generated, grouped by constituent. The results are sorted by descending proposal_count, and then descending sum of notional buys & sells.

# Get Requests
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-requests

GET /api/v1/custom/org/{organization_uuid}/reports/requests/
List all authenticated requests. Note that requests which fail to match a valid path are not included in these statistics.

# Get Aggregate Request Metrics
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-requests-aggregate

GET /api/v1/custom/org/{organization_uuid}/reports/requests/aggregate/
Get aggregate statistics for all authenticated requests. Note that requests which fail to match a valid path are not included in these statistics.

# Get Ticker Constraints
Source: https://docs.tilt.now/api-reference/endpoint/get-org-reports-ticker-constraints

GET /api/v1/custom/org/{organization_uuid}/reports/ticker_constraints/
Get a list of ticker constraints across all clients, including at the organization level.

# Get Organization Risk Model
Source: https://docs.tilt.now/api-reference/endpoint/get-org-risk-model

GET /api/v1/custom/org/{organization_uuid}/risk_model

Optimizer factor bounds use built-in allocation factors or organization-configured custom loadings. Use [Get Organization](/api-reference/endpoint/get-org-details) to inspect `factor_values`. See [Optimizer factor bounds](/customization/factor-bounds) before mapping risk-model factors to optimizer constraints.


# Get Portfolio Config
Source: https://docs.tilt.now/api-reference/endpoint/get-portfolio-config

GET /api/v1/custom/org/{organization_uuid}/portfolio_configs/{config_uuid}/
Retrieve a portfolio config for the organization

# Get Portfolio Configs
Source: https://docs.tilt.now/api-reference/endpoint/get-portfolio-configs

GET /api/v1/custom/org/{organization_uuid}/portfolio_configs/
List portfolio configs for the organization

# Get Tilt
Source: https://docs.tilt.now/api-reference/endpoint/get-tilt-details

api-reference/openapi-schema.json GET /api/v1/tilts/{tilt_uuid}
Retrieves stored Marketplace display data for a Tilt owned by the API key's organization.

# List Account Backtests
Source: https://docs.tilt.now/api-reference/endpoint/list-account-backtests

GET /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/backtests/
List all backtest jobs for a client

# List Preview Jobs
Source: https://docs.tilt.now/api-reference/endpoint/list-dynamic-rules-preview-jobs

GET /api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/jobs/

# List Indexes
Source: https://docs.tilt.now/api-reference/endpoint/list-indexes

GET /api/v1/indexes
Returns all indexes your account is subscribed to.

# List Tilts
Source: https://docs.tilt.now/api-reference/endpoint/list-tilts

api-reference/openapi-schema.json GET /api/v1/tilts
Returns the current version of each Tilt owned by the API key's organization. Drafts and published Tilts are returned by default.

# Update Asset Class
Source: https://docs.tilt.now/api-reference/endpoint/patch-asset-classes

PATCH /api/v1/custom/org/{organization_uuid}/asset_classes/{asset_class_uuid}/
Update asset class data

# Update Client Account
Source: https://docs.tilt.now/api-reference/endpoint/patch-client-account

PATCH /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}
View for retrieving and updating a specific client account.

Supports:
- GET: Retrieve account details with holdings and portfolio data
- PATCH: Update account data

Use `customization_config.factor_exposure_bounds` to constrain factor exposure. See [Optimizer factor bounds](/customization/factor-bounds) for accepted names, units, and the active reference, or [Configure factor exposure bounds](/customization/configure-factor-bounds) for account-update examples and the custom-factor upload format, which is in development.


# Update Portfolio Config
Source: https://docs.tilt.now/api-reference/endpoint/patch-portfolio-configs

PATCH /api/v1/custom/org/{organization_uuid}/portfolio_configs/{config_uuid}/
Update a portfolio config for the organization

# Create Account Backtest
Source: https://docs.tilt.now/api-reference/endpoint/post-account-backtest

POST /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/backtests/
Start a new backtest job for a client

# Optimize Account Portfolio
Source: https://docs.tilt.now/api-reference/endpoint/post-account-optimize

POST /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/optimize/
Get the customized weights for a client.

# Create Account Trade Proposal
Source: https://docs.tilt.now/api-reference/endpoint/post-account-proposal

POST /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/proposal/
Create a rebalance proposal for a client.

# Create Asset Class
Source: https://docs.tilt.now/api-reference/endpoint/post-asset-class

POST /api/v1/custom/org/{organization_uuid}/asset_classes/
Create a new asset class in the organization

# Create Bulk Optimization Task
Source: https://docs.tilt.now/api-reference/endpoint/post-bulk-client-optimize-proposal

POST /api/v1/custom/org/{organization_uuid}/optimized_proposals/
Create optimized portfolio proposals for multiple client accounts in bulk.

This endpoint creates proposals asynchronously. Optimization errors (infeasible/unbounded problems)
will be handled during the async task execution and reflected in the proposal's status and failure_reason field.

Create tasks to optimize portfolio and generate proposals for multiple clients.


# Create Client Account
Source: https://docs.tilt.now/api-reference/endpoint/post-client-account

POST /api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/
Create a new account under an existing client

# Create Preview Job
Source: https://docs.tilt.now/api-reference/endpoint/post-dynamic-rules-preview

POST /api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/

# Simulate Dynamic Rules
Source: https://docs.tilt.now/api-reference/endpoint/post-dynamic-rules-simulate

POST /api/v1/custom/org/{organization_uuid}/dynamic_rules/simulate/

# Validate Expression
Source: https://docs.tilt.now/api-reference/endpoint/post-dynamic-rules-validate

POST /api/v1/custom/org/{organization_uuid}/dynamic_rules/validate/

# Create Client
Source: https://docs.tilt.now/api-reference/endpoint/post-org-client

POST /api/v1/custom/org/{organization_uuid}/clients/
Create a new client in the organization

# Create Organization Risk Model
Source: https://docs.tilt.now/api-reference/endpoint/post-org-risk-model

POST /api/v1/custom/org/{organization_uuid}/risk_model

# Create Portfolio Config
Source: https://docs.tilt.now/api-reference/endpoint/post-portfolio-config

POST /api/v1/custom/org/{organization_uuid}/portfolio_configs/
Create a new portfolio config for the organization

# Update Client
Source: https://docs.tilt.now/api-reference/endpoint/put-client-update

PATCH /api/v1/custom/org/{organization_uuid}/clients/{uuid}/
View for retrieving and updating organization clients.

Supports:
- GET: Retrieve client details
- PATCH: Update the client's external ID and metadata. Holdings and
  account settings still update a client with exactly one account; a
  client with more updates each account at its own endpoint.

# Update Organization Risk Model
Source: https://docs.tilt.now/api-reference/endpoint/put-org-risk-model

PUT /api/v1/custom/org/{organization_uuid}/risk_model

# Search Optimization Proposals
Source: https://docs.tilt.now/api-reference/endpoint/search-optimized-proposals

POST /api/v1/custom/org/{organization_uuid}/optimized_proposals/list/

# Search Tickers
Source: https://docs.tilt.now/api-reference/endpoint/search-tickers

api-reference/openapi-schema.json GET /api/v1/tickers/search
Search for tickers, filtering by ticker property. At least one filter property must be provided. The searchable universe is Tilt's listed-security index (equities, ETFs, and related types); brokerage-specific instruments outside it — e.g. event-contract market tickers such as Kalshi markets, or spot crypto — are never indexed: searching for them returns zero results, not an error.

# Update Organization
Source: https://docs.tilt.now/api-reference/endpoint/update-org-details

PATCH /api/v1/custom/org/{organization_uuid}/

Custom-factor upload is in development; contact the [Tilt team](mailto:contact@tilt.now) to request a factor and confirm setup. The [upload format reference](/customization/configure-factor-bounds#custom-factor-uploads-in-development) documents `factor_values`, which replaces all existing custom factor values for the organization when supplied. See [Optimizer factor bounds](/customization/factor-bounds) for built-in factor names and custom-loading units.


# Apply construction
Source: https://docs.tilt.now/api-reference/index-construction-preview/apply-construction

api-reference/index-construction-preview-openapi.yaml PATCH /api/v1/tilts/{tilt_uuid}
Save and evaluate a Tilt methodology atomically.

# Backtest a Tilt
Source: https://docs.tilt.now/api-reference/index-construction-preview/backtest-tilt

api-reference/index-construction-preview-openapi.yaml GET /api/v1/tilts/{tilt_uuid}/backtest
Backtest a saved Tilt methodology over a date range.

The backtest uses the Tilt's saved methodology. Set `MONTHLY`, `QUARTERLY`,
`SEMI_ANNUALLY`, or `ANNUALLY` in `rules.rebalancing_period` when you
[apply construction](/api-reference/index-construction-preview/apply-construction).
The date parameters select the analysis window; they do not change the cadence.

Add `benchmark` for benchmark returns, relative performance, and risk
statistics. Omit it for a portfolio-only result.


# Create a Tilt
Source: https://docs.tilt.now/api-reference/index-construction-preview/create-tilt

api-reference/index-construction-preview-openapi.yaml POST /api/v1/tilts
Create an unevaluated rules-based equity draft.

# Get evaluated constituents
Source: https://docs.tilt.now/api-reference/index-construction-preview/get-constituents

api-reference/index-construction-preview-openapi.yaml GET /api/v1/tilts/{tilt_uuid}/constituents
Get a complete saved constituent snapshot with scores and weights.

# Get a Tilt
Source: https://docs.tilt.now/api-reference/index-construction-preview/get-tilt

api-reference/index-construction-preview-openapi.yaml GET /api/v1/tilts/{tilt_uuid}
Get a Tilt and its saved methodology.

# Inspect a construction field
Source: https://docs.tilt.now/api-reference/index-construction-preview/inspect-catalog-field

api-reference/index-construction-preview-openapi.yaml POST /api/v1/catalog/inspect
Inspect field metadata, coverage, and distribution.

# List the construction catalog
Source: https://docs.tilt.now/api-reference/index-construction-preview/list-catalog

api-reference/index-construction-preview-openapi.yaml GET /api/v1/catalog
Browse every field and trailing-window capability available to construction rules.

# List Tilts
Source: https://docs.tilt.now/api-reference/index-construction-preview/list-tilts

api-reference/index-construction-preview-openapi.yaml GET /api/v1/tilts
List Tilts in the API key organization.

# List universe presets
Source: https://docs.tilt.now/api-reference/index-construction-preview/list-universe-presets

api-reference/index-construction-preview-openapi.yaml GET /api/v1/catalog/universe_presets
Discover valid candidate-universe preset IDs.

# Search the construction catalog
Source: https://docs.tilt.now/api-reference/index-construction-preview/search-catalog

api-reference/index-construction-preview-openapi.yaml POST /api/v1/catalog/search
Discover fields and expression functions.

# Search RBICS classifications
Source: https://docs.tilt.now/api-reference/index-construction-preview/search-rbics

api-reference/index-construction-preview-openapi.yaml POST /api/v1/catalog/rbics
Find classifications and ready-to-use filter expressions.

# Resolve ticker listings
Source: https://docs.tilt.now/api-reference/index-construction-preview/search-tickers

api-reference/index-construction-preview-openapi.yaml GET /api/v1/tickers/search
Resolve security listings for construction overrides.

> [!NOTE]
>
> CUSIP and ISIN are licensed identifiers. Filtering by either identifier
> requires the API key's organization to have access to CGS Identifiers;
> otherwise the request returns `403`. In all search results, `cusip` and `isin`
> are `null` unless the organization has that access.


# Pulse API
Source: https://docs.tilt.now/backchannel/introduction

Market scenarios, risk analysis, company news, and company search for your own applications.

## Welcome

The Pulse API exposes Tilt's market intelligence primitives for external integrations. The public v1 surface is intentionally narrow: scenarios, topics, company search, company news, and risk analysis.

> [!NOTE]
>
> The retired mobile-only Backchannel routes are not part of the application or the public Pulse contract.

## What You Can Build

> [card] Market Scenarios
>
> Search and display curated market scenarios with impact analysis relevant to your users' holdings.

> [card] Risk Analysis
>
> Surface macro sensitivities and run scenario-based risk analysis against portfolios.

> [card] Topics & News
>
> Deliver market topics, expert commentary, and company-specific news feeds.

> [card] Company Lookup
>
> Resolve companies into Tilt's current v1 entity identifiers before calling downstream analysis endpoints.

## Get started

> [card] [Quick start](/backchannel/quick-start)
>
> Authenticate and make your first API calls in minutes

> [card] [Search Scenarios](/api-reference/backchannel/search-scenarios)
>
> Explore the scenarios endpoint


# Portfolio feed guide
Source: https://docs.tilt.now/backchannel/portfolio-feed-guide

One call that turns a portfolio and a few interests into the news that matters, grouped into titled stories and topics, ranked, with the impact on each holding.

## Overview

The Portfolio Feed answers "what happened in the last day or two that matters to this portfolio?" in a single request. You send a portfolio, optionally a few interests and a time window; you get back the window's Dow Jones articles grouped into titled stories, ranked so the day's biggest news leads and a story about one of your holdings is lifted in proportion to the position, with each article carrying its portfolio exposure.

Everything expensive happens when an article is ingested: its importance rating, its story assignment and title, its scenario tree. A feed call only selects and ranks, so it returns in tens of milliseconds and can be made on every page load.

## The request

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/feed" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_weights": {"MH33D6-R": 0.4, "037833100": 0.3, "P8R3C2-R": 0.3},
    "queries": [{"query": "artificial intelligence", "weight": 1.0}],
    "window_hours": 48,
    "topic_grouping": true
  }'
```

* `portfolio_weights` is keyed by Tilt asset id or CUSIP; the two can be mixed. Weights are read as portfolio shares, so they should sum to one. See the [Scenario analysis guide](/backchannel/scenario-analysis-guide) for resolving tickers.
* `queries` is optional. Without it the feed is every article in the window ranked by importance, with your holdings blended in. With it, articles are selected by similarity to the interests and importance still drives the order.
* `window_hours` defaults to 48 and goes up to 168 (a week).
* `topic_grouping` adds a second, broader layer on top of the stories (see below).

Every other field has a default that matches how the feed is tuned; the reference page lists them.

## The response

```json theme={null}
{
  "success": true,
  "window_since": "2026-09-06T17:00:00+00:00",
  "articles_considered": 150,
  "stories_considered": 145,
  "groups_total": 131,
  "groups": [
    {
      "group_id": "story-8f3c…",
      "title": "U.S. Strikes Three Iranian Ships After Missiles Fired at American Aircraft Carrier",
      "title_source": "story",
      "score": 0.9,
      "rank": 0.9,
      "max_importance": 9,
      "story_count": 1,
      "holdings": [],
      "holdings_weight": 0.0,
      "portfolio_exposure": {"mad_pct": 1.8, "expected_return_pct": -0.6, "article_point_id": "…"},
      "articles": [{"headline": "…", "tilt_source": "WSJ", "importance_rating": 9, "portfolio_exposure": {"…": "…"}}]
    },
    {
      "group_id": "story-2a91…",
      "title": "GE Aerospace to Buy Consolidated Precision Products for $11.4 Billion",
      "title_source": "story",
      "score": 0.7,
      "rank": 0.722,
      "max_importance": 7,
      "holdings": ["G6Y2KQ-R"],
      "holdings_weight": 0.0055,
      "articles": [{"…": "…"}]
    }
  ],
  "topics": [
    {
      "topic_id": "story-8f3c…",
      "title": "Middle East Geopolitical Risk",
      "title_source": "subject_code",
      "story_count": 5,
      "article_count": 6,
      "max_importance": 9,
      "holdings": [],
      "groups": [{"…": "…"}]
    }
  ],
  "warnings": []
}
```

`groups` is the feed, in order. Each group is one story: its `title`, the `articles` that tell it (one per vendor version, the best first), `max_importance` on the 1 to 10 scale the pipeline assigns at ingest, the `holdings` it touches and their combined share of the portfolio, and `portfolio_exposure`, the exposure of the group's most exposed article. Each article also carries its own `portfolio_exposure`, and `include_scenarios: true` returns the scenario tree behind it.

## How articles are grouped

Two layers, both computed before you call.

**Stories** are the groups. When an article is ingested it is matched against the last seven days of articles on its headline and opening paragraph; articles that describe the same event share one story and one title, written once for the story. A re-issued article ("-- 2nd Update") folds into the same story. `title_source` tells you where a title came from: `story` for the pipeline's title, `subject_code` when a story is titled by a subject code its articles share, `headline` when it falls back to the lead headline.

**Topics**, returned when `topic_grouping` is true, gather several stories into a broader thread: the Iran strikes, the Houthi attack on Saudi energy and the oil price reaction become one *Middle East Geopolitical Risk* topic. A topic is titled by the subject code most of its stories share, or by its leading story. The groups inside a topic are the same objects as in `groups`, in the same order, so a client can render either view from one response.

## How the feed is ranked

The order is by `rank`, which is the story's best article score plus a holdings lift:

* The score is importance, so a 9 leads an 8 whatever the portfolio. Iran sending missiles outranks a routine note about a large holding.
* A story tagged to one of your holdings, rated at least 4, is lifted by up to two importance points, in proportion to the position: a 5% position or larger earns the full lift, a 1% position a fifth of it. A major story about a company that is all of a portfolio rises near the top; broad company news does not displace the day's biggest events.
* Within a story, a WSJ article leads when its score is within a small margin of the story's best, so the higher-quality version is the one shown first. `source_preference` changes the vendors, `[]` disables it.

`holdings_boost`, `full_boost_share` and `holdings_min_importance` tune the lift; the defaults are what the examples above use.

## Practical notes

* Latency is tens of milliseconds for a portfolio-only call. Interest queries add an embedding step for headlines the pipeline has not seen; expect under a second for a seven-day window.
* Send the portfolio on each call; nothing is stored between calls.
* Identical calls return identical order.
* `min_importance` drops minor items; `limit_groups` and `max_per_group` size the page.
* The feed draws on the article sources your organization is entitled to: Wall Street Journal stories, Dow Jones Newswires items, and MarketBrief stories are each licensed separately. `sources` (their tags: `WSJ`, `DJ`, `MarketBrief`) narrows the feed to some of them; naming a source your organization is not entitled to returns a 403 that names it. The response's `sources` lists what the feed was drawn from.


# Pulse API quick start
Source: https://docs.tilt.now/backchannel/quick-start

Authenticate and start making Pulse API calls

## Overview

### Base URL

```bash theme={null}
https://tilt.io
```

### Authentication

All public Pulse API endpoints require an API key.

Include the API key in the header of each request:

```bash theme={null}
X-Api-Key: <your_api_key>
```

> [!NOTE]
>
> Reuse your existing Tilt API key. Pulse does not issue a separate key type in v1.

## Making Your First API Calls

### 1. Search Scenarios

Search for relevant market scenarios:

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"weight": 1, "query": "tariffs"}],
    "limit": 5
  }'
```

[View full API reference →](/api-reference/backchannel/search-scenarios)

### 2. Get Scenario Detail

Fetch a single scenario by ID:

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/POINT_ID" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "include_content": true
  }'
```

[View full API reference →](/api-reference/backchannel/get-scenario)

### 3. Get Macro Sensitivities

Analyze how macro factors affect a portfolio:

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/risk/sensitivities" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tilt_ids": ["Q2YN1N-R"],
    "limit": 10
  }'
```

[View full API reference →](/api-reference/backchannel/get-macro-sensitivities)

### Public v1 Scope

> [!NOTE]
>
> The public Pulse API is limited to scenarios, topics, company search, company news, and risk analysis. End-user account, holdings, and brokerage operations are not part of the public contract.


# Scenario analysis guide
Source: https://docs.tilt.now/backchannel/scenario-analysis-guide

Analyze how news events and macro shocks affect a portfolio using the Pulse API.

## Overview

The Pulse API lets you answer three core questions about a portfolio:

1. **"What would happen to my portfolio if X occurred?"** — Describe any scenario in plain English and get a probability-weighted impact analysis.
2. **"How does this Dow Jones article affect my holdings?"** — Fetch a pre-computed article scenario and calculate its portfolio exposure.
3. **"What happens if macro conditions change?"** — Run what-if analysis with specific macro factor shocks (USD strength, oil prices, etc.).

All workflows require a portfolio expressed as a map of `tilt_asset_id → weight`. This guide walks through resolving tickers, building portfolio weights, and calling the scenario and risk endpoints.

> [!TIP]
>
> Looking for the article-scenarios endpoint? The public Pulse route is `POST /api/v1/backchannel/scenarios/{id}`. See [Analyze a Pre-Computed Dow Jones Article](#step-5-analyze-a-pre-computed-dow-jones-article).

## Step 1: Resolve Tickers to Tilt Asset IDs

All portfolio-related endpoints accept weights keyed by **Tilt Asset ID** — an internal identifier for each security. Use the Search Tickers endpoint to resolve symbols.

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/tickers/search?symbols=AAPL,MSFT,NVDA" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "count": 6,
  "results": [
    {
      "symbol": "AAPL",
      "name": "Apple, Inc.",
      "exchange": "NAS",
      "ticker_type": "common_stock",
      "tilt_asset_id": "MH33D6-R"
    },
    {
      "symbol": "AAPL",
      "name": "Apple, Inc.",
      "exchange": "TSE",
      "ticker_type": "dr",
      "tilt_asset_id": "W0R2RY-R"
    },
    ...
  ]
}
```

> [!NOTE]
>
> A symbol may return multiple results across exchanges (e.g. NAS and TSE listings). Filter by `ticker_type: "common_stock"` and the relevant exchange to get the primary US listing.

Extract the `tilt_asset_id` from each result.

[View API Reference →](/api-reference/endpoint/search-tickers)

> [!TIP]
>
> You can resolve multiple symbols in a single call by passing a comma-separated list. Cache the mapping — tilt asset IDs are stable identifiers that don't change.

## Step 2: Build Portfolio Weights

Construct a `portfolio_weights` object mapping each `tilt_asset_id` to a decimal weight (summing to 1.0):

```json theme={null}
{
  "MH33D6-R": 0.40,
  "P8R3C2-R": 0.35,
  "K7TPSX-R": 0.25
}
```

> [!NOTE]
>
> Weights should sum to 1.0. If they don't, the API will still work but exposure calculations will be proportional to the weights provided.

This `portfolio_weights` object is reused across all the endpoints below.

## Step 3: Scenario Portfolio Analysis

The simplest way to analyze portfolio impact. Describe any scenario in plain English and the API generates a probability tree of outcomes with portfolio-level returns.

### Recommended: Use `flat_scenarios` mode

We recommend using `flat_scenarios: true` for most integrations. This generates a clean, single-level structure where each scenario directly contains its macro shocks — no nested sub-scenarios to traverse. The result is simpler to parse and display.

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/risk/scenario_portfolio_analysis" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_description": "China begins naval blockade of Taiwan, semiconductor supply chain completely severed",
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "flat_scenarios": true,
    "search_for_context": true,
    "include_security_details": true
  }'
```

### Key parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `scenario_description` | string | — | Plain English description of the scenario to analyze. |
| `portfolio_weights` | object | — | Map of `tilt_asset_id` → weight. |
| `as_of_date` | string | today | Date for the analysis (YYYY-MM-DD). |
| `flat_scenarios` | boolean | `false` | **Recommended: `true`.** Generates flat scenarios where each scenario directly contains its macro shocks. When `false`, generates a two-level tree with sub-scenarios. |
| `search_for_context` | boolean | `true` | Search for relevant background articles to improve scenario quality. |
| `include_security_details` | boolean | `true` | Include per-security breakdown in each leaf scenario. |
| `aggregate_scenarios` | boolean | `false` | Collapse the scenario tree into summary stats (mean/std per top-level scenario). |
| `force_regenerate` | boolean | `false` | Bypass the scenario cache and regenerate from scratch. |

### Caching behavior

Scenario generation results are **automatically cached**. The first call for a given scenario generates fresh results (10–15 seconds). All subsequent calls with the same `scenario_description`, `as_of_date`, `search_for_context`, and `flat_scenarios` combination return cached results in **under 1 second**.

The cache is keyed on these four parameters. The portfolio weights are **not** part of the cache key — portfolio impact computation happens after scenario generation, so a single cached scenario tree can be reused for any portfolio instantly.

> [!TIP]
>
> For a Dow Jones article that has already been processed, do not send the article text to this endpoint. Use the pre-computed article scenario endpoint in Step 5. Reserve `scenario_portfolio_analysis` for hypothetical scenarios and articles that do not have a pre-computed scenario.

If you only need to rank articles by their relevance to a portfolio, use [Article Portfolio Relevance](/api-reference/backchannel/article-portfolio-relevance). It returns a comparable score without generating the scenario tree or per-security scenario returns.

Use `force_regenerate: true` to bypass the cache if you need fresh results for an already-cached scenario.

### Response structure

The response includes an AI-generated scenario tree, leaf-level portfolio impacts, and a probability-weighted expected return:

```json theme={null}
{
  "success": true,
  "scenario_description": "China begins naval blockade of Taiwan...",
  "as_of_date": "2026-03-10",
  "expected_portfolio_return_pct": -0.0607,
  "cache_hit": true,
  "portfolio_summary": {
    "num_scenarios": 3,
    "num_leaf_scenarios": 3,
    "num_securities": 3
  },
  "scenario_tree": [
    {
      "probability": 40,
      "title": "Full blockade with military escalation",
      "description": "...",
      "macro_shocks": [
        {"indicator": "VIXCLS", "impact": 0.25},
        {"indicator": "rbics_55", "impact": -0.15}
      ]
    }
  ],
  "leaf_scenarios": [
    {
      "path": ["Full blockade with military escalation"],
      "joint_probability_pct": 40,
      "portfolio_return_pct": -0.12,
      "portfolio_expected_return_pct": -0.12,
      "contribution_to_expected_return_pct": -0.048,
      "top_movers": [
        {"tilt_id": "K7TPSX-R", "ticker": "NVDA", "expected_return_pct": -0.22, "contribution_to_portfolio_pct": -0.055},
        {"tilt_id": "P8R3C2-R", "ticker": "MSFT", "expected_return_pct": 0.01, "contribution_to_portfolio_pct": 0.004}
      ],
      "security_details": [
        {
          "tilt_id": "MH33D6-R",
          "ticker": "AAPL",
          "company_name": "Apple, Inc.",
          "weight": 0.40,
          "expected_return_pct": -0.1559,
          "contribution_to_portfolio_pct": -0.0624,
          "factor_contributions": {}
        }
      ]
    }
  ],
  "context_articles": ["Taiwan Export Growth Lost Momentum in February", "..."],
  "context_article_ids": ["a1b2c3d4-...", "e5f6g7h8-..."],
  "warnings": null,
  "generated_at": "2026-03-10T14:30:00"
}
```

> [!NOTE]
>
> When `flat_scenarios: true`, each scenario in `scenario_tree` contains its `macro_shocks` directly (no `sub_scenarios`), and `leaf_scenarios` has one entry per scenario. When `flat_scenarios: false` (default), scenarios have nested `sub_scenarios` and `leaf_scenarios` contains one entry per sub-scenario with joint probabilities.

**Key fields:**

| Field | Description |
| - | - |
| `expected_portfolio_return_pct` | Probability-weighted expected portfolio return across all leaf scenarios, in percentage points (1.0 = 1%). |
| `portfolio_summary` | Counts of scenarios, leaf scenarios, and securities analyzed. |
| `scenario_tree` | The full probability tree. Flat when `flat_scenarios: true`, nested with `sub_scenarios` when `false`. |
| `leaf_scenarios` | Flattened leaf nodes with joint probabilities, portfolio returns, top movers, and per-security details. |
| `leaf_scenarios[].portfolio_return_pct` | Portfolio return for this specific leaf scenario. |
| `leaf_scenarios[].contribution_to_expected_return_pct` | This leaf's contribution to the overall expected return (joint\_probability \* portfolio\_return). |
| `leaf_scenarios[].top_movers` | Top 3 gainers and top 3 losers by contribution to portfolio return. |
| `context_articles` | Headlines of articles used as background context (when `search_for_context` is true). |
| `context_article_ids` | Point IDs of context articles used as background context. |
| `cache_hit` | `true` if the scenario tree was served from cache, `false` if freshly generated. |
| `warnings` | Array of warnings (e.g., unknown tilt\_ids skipped). `null` if no warnings. |

> [!NOTE]
>
> This endpoint uses AI to generate scenarios on first encounter (\~10–15 seconds). Cached scenarios return in under 1 second. For instant results on pre-computed news scenarios, use the Search Scenarios endpoint below instead.

[View API Reference →](/api-reference/backchannel/scenario-portfolio-analysis)

### Flat vs. hierarchical scenarios

| | `flat_scenarios: true` | `flat_scenarios: false` (default) |
| - | - | - |
| **Structure** | 3 top-level scenarios, each with `macro_shocks` directly | 3–5 top-level scenarios, each with one or more `sub_scenarios` containing `macro_shocks` |
| **Leaf count** | 3 leaves (one per scenario) | Variable; one leaf per sub-scenario |
| **Best for** | Simple UIs, mobile cards, quick summaries | Detailed analysis, drill-down interfaces |
| **Parse complexity** | Flat list — no nesting to traverse | Two levels of nesting |

## Step 4: Search News Scenarios with Portfolio Exposure

Search for curated, pre-computed news scenarios and see how each one affects your portfolio. This is instant (no AI generation) and useful for browsing recent events.

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"weight": 1, "query": "tariffs trade war"}],
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "aggregate_scenarios": true,
    "limit": 5
  }'
```

### Key parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `queries` | array | — | Weighted search queries. Each has `query` (string) and `weight` (0–1). |
| `subject_code` | string | `null` | Filter by subject code (e.g. `"Technology"`, `"Tariffs & Trade"`). Can be used alone or with `queries`. |
| `portfolio_weights` | object | `null` | Map of `tilt_asset_id` → weight. When provided, each result includes a `portfolio_exposure` field. |
| `aggregate_scenarios` | boolean | `false` | When `true`, collapses the scenario tree into probability-weighted summary stats. |
| `order_by_exposure` | boolean | `false` | When `true`, sorts results by portfolio impact instead of relevance. Requires `portfolio_weights`. |
| `limit` | integer | `10` | Number of results (1–100). |
| `min_importance` | integer | `null` | Filter to scenarios with importance rating >= this value (1–10). |

> [!NOTE]
>
> At least one of `queries` or `subject_code` must be provided. Sending an empty request body will return a `422 Validation Error`.

### Response structure

The response wraps results in `articles`. Each article is a news scenario with timeline, probability tree, and (when `portfolio_weights` is provided) portfolio exposure:

```json theme={null}
{
  "success": true,
  "articles_found": 5,
  "articles": [
    {
      "point_id": "3fb7a574-c0d7-53b0-96cc-b98a2882f1c7",
      "headline": "Nvidia Invests in Mira Murati's Thinking Machines Lab",
      "date": "2026-03-10T00:00:00",
      "tilt_source": "WSJ",
      "importance_rating": 6,
      "timeline": [
        {"date": "2024-09-28", "summary": "OpenAI CTO Mira Murati resigns amid tensions"},
        {"date": "2026-01-26", "summary": "Nvidia invests $2B in CoreWeave for 5GW AI-factories"}
      ],
      "scenarios": [
        {
          "probability": 34,
          "title": "Compute-fueled breakout",
          "description": "Thinking Machines converts Nvidia's investment into a fast ramp of training and inference capacity...",
          "macro_shocks": [
            {"indicator": "rbics_55", "impact": 0.012},
            {"indicator": "VIXCLS", "impact": -0.6},
            {"indicator": "company_K7TPSX-R", "impact": 0.09}
          ],
          "sub_scenarios": [
            {
              "probability": 60,
              "title": "Frontier model debut",
              "description": "...",
              "macro_shocks": [...]
            }
          ]
        }
      ],
      "portfolio_exposure": {
        "expected_return_pct": 0.0049,
        "mad_pct": 0.0441,
        "num_leaf_scenarios": 8,
        "scenario_level_details": [
          {
            "title": "Compute-fueled breakout",
            "probability_pct": 34,
            "portfolio_return_mean_pct": 0.0693,
            "portfolio_return_std_pct": 0.0309,
            "sub_scenario_count": 2
          }
        ]
      }
    }
  ]
}
```

**Key fields in `portfolio_exposure`:**

| Field | Description |
| - | - |
| `expected_return_pct` | Probability-weighted expected portfolio return across all leaf scenarios, in percentage points (1.0 = 1%). |
| `mad_pct` | Probability-weighted median absolute portfolio return across leaf scenarios, in percentage points. |
| `num_leaf_scenarios` | Number of leaf nodes in the scenario tree used for the calculation. |
| `scenario_level_details` | Per-scenario breakdown with mean return, standard deviation, and sub-scenario count. |

[View API Reference →](/api-reference/backchannel/search-scenarios)

## Step 5: Analyze a Pre-Computed Dow Jones Article

Dow Jones articles are processed into article scenarios after ingestion. Once you have the scenario `point_id`, fetch the article's timeline, probability tree, macro and company shocks, related securities, and optional portfolio exposure:

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/scenarios/3fb7a574-c0d7-53b0-96cc-b98a2882f1c7" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "include_content": true,
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "aggregate_scenarios": false
  }'
```

`{id}` must be the article scenario's `point_id`, such as the value returned by the search endpoint in Step 4. It is not the source Dow Jones article ID. The current public endpoint does not resolve a raw Dow Jones article ID directly.

When `portfolio_weights` is provided, the response includes `portfolio_exposure` with probability-weighted expected return, median absolute return, and per-leaf portfolio returns. When `aggregate_scenarios` is `true`, the per-leaf detail is replaced by scenario-level mean and standard-deviation summaries.

> [!NOTE]
>
> If your integration warms the user's portfolio data before this request, retain the resulting weights and include them as `portfolio_weights`. This endpoint currently accepts portfolio weights rather than a user ID.

[View API Reference →](/api-reference/backchannel/get-scenario)

## Step 6: Macro Factor Analysis

### Get Macro Sensitivities

Understand which macro factors your portfolio is most exposed to:

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/risk/sensitivities" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "limit": 5
  }'
```

The response ranks macro factors by portfolio-level exposure, showing which factors would move your portfolio the most:

```json theme={null}
{
  "success": true,
  "type": "portfolio",
  "valid_securities": 3,
  "total_weight": 1,
  "portfolio_macro_exposures": [
    {
      "macro_factor": "macro_DTWEXBGS",
      "description": "US Dollar Index (Trade Weighted)",
      "portfolio_exposure": -2.1324,
      "top_contributors": [
        {"tilt_id": "MH33D6-R", "weight": 0.4, "sensitivity": -2.0164, "contribution": -0.8065},
        {"tilt_id": "K7TPSX-R", "weight": 0.25, "sensitivity": -3.1648, "contribution": -0.7912},
        {"tilt_id": "P8R3C2-R", "weight": 0.35, "sensitivity": -1.5277, "contribution": -0.5347}
      ]
    }
  ]
}
```

[View API Reference →](/api-reference/backchannel/get-macro-sensitivities)

### Run a Macro Scenario

Use the sensitivities output to stress-test with specific macro shocks. The `shocks` object maps factor identifiers to shock magnitudes in standard deviations.

> [!NOTE]
>
> The sensitivities endpoint returns factor names with a `macro_` prefix (e.g. `macro_DTWEXBGS`). When passing shocks to the scenario endpoint, **drop the prefix** — use the raw identifier (e.g. `DTWEXBGS`).

```bash theme={null}
curl -X POST "https://tilt.io/api/v1/backchannel/risk/scenario" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_weights": {
      "MH33D6-R": 0.40,
      "P8R3C2-R": 0.35,
      "K7TPSX-R": 0.25
    },
    "shocks": {
      "DTWEXBGS": 0.5
    },
    "include_security_details": true
  }'
```

The response shows the expected portfolio return and per-security breakdown:

```json theme={null}
{
  "success": true,
  "portfolio_expected_return_pct": -1.0662,
  "shocks_applied": {
    "DTWEXBGS": 0.5
  },
  "factor_summary": [
    {
      "factor": "DTWEXBGS",
      "type": "fred",
      "description": "US Dollar Index (Trade Weighted)",
      "shock": 0.5,
      "portfolio_impact_pct": -1.0662
    }
  ],
  "security_details": [
    {
      "tilt_id": "MH33D6-R",
      "ticker": "AAPL",
      "company_name": "Apple, Inc.",
      "weight": 0.40,
      "expected_return_pct": -0.8066,
      "contribution_to_portfolio_pct": -0.3226,
      "factor_contributions": {
        "DTWEXBGS": -0.8066
      }
    }
  ]
}
```

[View API Reference →](/api-reference/backchannel/run-macro-scenario)

## Putting It Together

A typical integration flow:

1. **Resolve tickers** once and cache the `tilt_asset_id` mapping.
2. **Run scenario portfolio analysis** with a plain English description to quickly assess portfolio impact for any hypothetical event. Use `flat_scenarios: true` for the simplest response structure. This is the easiest starting point.
3. **Search news scenarios** with `portfolio_weights` to find real-world events that matter to the portfolio. Use `order_by_exposure: true` to surface the highest-impact stories first.
4. **Fetch individual scenarios** with `portfolio_weights` for detailed drill-down with leaf-level probability breakdowns.
5. **Get macro sensitivities** to understand the portfolio's factor exposures.
6. **Run macro scenarios** to stress-test against specific factor shocks (e.g., "what if the US Dollar Index rises 0.5 standard deviations?").

> [!TIP]
>
> **Scenario Portfolio Analysis** (Step 2) generates scenarios on-the-fly using AI. The first call takes \~10–15 seconds, but results are automatically cached — subsequent calls for the same scenario return in under 1 second, for any portfolio. **Search Scenarios** (Step 3) returns pre-computed news scenarios instantly. Use scenario portfolio analysis for hypothetical what-if questions, and search scenarios for browsing recent real-world events.

## Rate Limits

All endpoints are rate-limited at **120 requests per minute** per API key. The `scenario_portfolio_analysis` endpoint has an additional limit of **10 requests per minute** to protect the AI generation backend.

If you exceed the limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please slow down and try again."
}
```

## Error Handling

All error responses follow a consistent format:

```json theme={null}
{
  "error": "Error type",
  "message": "Human-readable description"
}
```

| Status Code | Meaning |
| - | - |
| `400` | Bad request (e.g., empty portfolio weights) |
| `401` | Missing, invalid, revoked, or expired credentials. Use the `X-Api-Key` header. |
| `415` | Unsupported Content-Type. Use `application/json`. |
| `422` | Validation error with field-level details |
| `429` | Rate limit exceeded |
| `500` | Internal server error |


# Configure factor exposure bounds
Source: https://docs.tilt.now/customization/configure-factor-bounds

Set account exposure bounds through the API and review the custom-factor upload format in development.

Use this guide to constrain an account's built-in asset-allocation exposure or a custom factor. Start with an existing organization, client account, and assigned portfolio. See the [Customization guide](/customization/guide) for account setup and [Optimizer factor bounds](/customization/factor-bounds) for factor names, units, and active-reference definitions.

To set bounds in the app, use the Advisor guide: [Set factor exposure bounds](/advisor/set-factor-exposure-bounds).

> [!NOTE]
>
> Custom-factor upload is in development. You can set bounds for built-in factors and custom factors already configured for your organization. Contact the [Tilt team](mailto:contact@tilt.now) to request a new factor. The [upload section](#custom-factor-uploads-in-development) documents its data format and replacement behavior.

The examples use API-key authentication. Replace the organization, client, and account placeholders with your own values. The ranges illustrate the request format; choose bounds for your portfolio.

## 1. Inspect the organization's custom factors

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/ \
  --header 'X-Api-Key: <api-key>'
```

Read `factor_values` in the response. It contains the existing custom factor names and asset loadings. Built-in `asset_allocation_*` factors do not require an entry here.

[Get Organization API reference](/api-reference/endpoint/get-org-details)

## 2. Set the account's exposure bounds

Set bounds in `customization_config.factor_exposure_bounds`. This example uses the built-in equity factor, which requires no custom upload:

```bash theme={null}
curl --request PATCH \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "customization_config": {
      "factor_exposure_bounds": [
        {
          "factor": "asset_allocation_equity",
          "min_bound": "0.50",
          "max_bound": "0.70",
          "min_active_bound": "-0.03",
          "max_active_bound": "0.03"
        }
      ]
    }
  }'
```

The equity row allows 50% to 70% absolute exposure and an active difference of −3 to +3 percentage points. Both absolute and active ranges apply together. To bound an existing custom factor, use its exact configured name and loadings' scale after confirming them with the Tilt team.

Provide all four numeric bounds for each factor. Include the complete factor-bound list you want saved at this account scope: submitting the list replaces its existing rows. A non-empty account list takes precedence over portfolio and organization lists. See [Configuration hierarchy](/customization/guide#configuration-hierarchy) before overriding inherited bounds.

[Update Client Account API reference](/api-reference/endpoint/patch-client-account)

## 3. Run and inspect the optimization

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/optimize/ \
  --header 'X-Api-Key: <api-key>'
```

Check the optimized holdings against the saved loadings and both ranges. For each factor, sum portfolio weight multiplied by asset loading, then subtract the same calculation for the optimization benchmark to check active exposure. Saving configuration alone does not establish that an optimization can satisfy it.

If a custom factor has no configured values, contact the [Tilt team](mailto:contact@tilt.now) to confirm its setup. If built-in asset-class exposure data is unavailable, ask the team to confirm data availability. For an infeasible run, review the absolute and active ranges together with the account's other constraints.

[Optimize Account Portfolio API reference](/api-reference/endpoint/post-account-optimize)

## Custom-factor uploads (in development)

Custom-factor upload is in development. The example below documents the upload data format for planned self-service support. Contact the Tilt team to request a factor and confirm setup before submitting custom loadings.

A custom factor has a name and a map from Tilt Asset IDs to numeric loadings. For a custom large-cap bucket, `1` identifies assets in the defined bucket and `0` identifies assets outside it. Its weighted exposure measures the portfolio allocation to that bucket.

```json theme={null}
{
  "factor_values": [
    {
      "name": "custom_large_cap",
      "values": {
        "<asset-id-in-large-cap-bucket>": "1.0",
        "<asset-id-outside-large-cap-bucket>": "0.0",
        "$USD": "0.0"
      }
    }
  ]
}
```

This illustrative payload describes `factor_values` on [Update Organization](/api-reference/endpoint/update-org-details). The values map needs coverage across holdings, the optimization benchmark, and potential purchases. Missing custom asset loadings count as zero, which can understate bucket exposure.

> [!WARNING]
>
> Supplying `factor_values` replaces the organization's entire custom-factor list. Retaining existing factors requires their names and complete values maps in the same request. Other accounts in the organization can use these loadings too; review their bounds before replacing a factor.

After the team confirms a custom factor is configured, use its exact name in the app or API bounds. A name entered in the bounds editor or a display label from monitoring does not create asset loadings.

To request another Tilt-supplied factor or help defining a new one, send the team the details listed in [Request a new factor](/customization/factor-bounds#request-a-new-factor).


# Optimizer factor bounds
Source: https://docs.tilt.now/customization/factor-bounds

Look up built-in allocation factors, custom loadings, exposure units, and benchmark-relative bounds.

A factor loading is a number assigned to an asset. The optimizer calculates portfolio exposure by multiplying each asset's loading by its portfolio weight and adding the results. Factor exposure bounds constrain that total.

Use [Configure factor exposure bounds](/customization/configure-factor-bounds) to save bounds through the API and look up the custom-factor upload format.

You can also [set factor exposure bounds in the app](/advisor/set-factor-exposure-bounds) for an account, model, or firm.

> [!NOTE]
>
> Custom-factor upload is in development. Use built-in factors or custom factors already configured for your organization. Contact the [Tilt team](mailto:contact@tilt.now) to request a new factor and confirm its availability.

## Built-in allocation factors

Tilt supplies these asset-allocation loadings when asset-class exposure data is available. You can reference their exact names in `customization_config.factor_exposure_bounds` without uploading custom values.

| Factor name | Exposure measured |
| - | - |
| `asset_allocation_equity` | Equity. |
| `asset_allocation_fixed_income` | Fixed income. |
| `asset_allocation_commodity` | Commodities. |
| `asset_allocation_currency` | Currency. |
| `asset_allocation_alternative` | Alternatives. |
| `asset_allocation_cash` | Cash. |
| `asset_allocation_private_equity` | Private equity. |
| `asset_allocation_crypto` | Crypto. |
| `asset_allocation_unknown` | Unclassified exposure. |

These loadings are fractions: a loading of `1` means 100% exposure to that asset-class type, and `0.6` means 60%. Tilt uses the latest asset-class exposure record on or before the optimization date. Cash receives a cash loading of `1`. For a direct equity holding without an exposure record, Tilt assigns an equity loading of `1`; other uncovered assets receive an unknown loading of `1`.

A holding can contribute to several allocation factors through its exposure record. A 10% portfolio weight in a fund with an equity loading of `0.6` contributes 6% equity exposure.

If an optimization reports that asset-class exposure data is unavailable, contact [Tilt Support](mailto:contact@tilt.now) to confirm data availability before using these factors.

## Custom factor names and loadings

Custom factors come from your organization's `factor_values`. Each entry has a `name` and a `values` map from Tilt Asset IDs to numeric loadings. Use that exact `name` as the bound's `factor` value. [Get Organization](/api-reference/endpoint/get-org-details) returns your configured factors. The [upload format](/customization/configure-factor-bounds#custom-factor-uploads-in-development) documents the integration contract for custom-factor upload, which is in development.

The `asset_allocation_` prefix is reserved for Tilt's built-in factors. Custom factor names use a different prefix, such as `custom_large_cap`.

The custom loading definition determines its scale and direction. A binary membership factor uses `1` for assets in the bucket and `0` for assets outside it. For a continuous score, confirm what higher and lower values mean before choosing bounds. The optimizer treats missing custom asset loadings as zero, so confirm coverage across the account's holdings and optimization benchmark, including assets it may buy.

## Absolute and active bounds

Each entry in `customization_config.factor_exposure_bounds` requires these fields:

| Field | Meaning |
| - | - |
| `factor` | A built-in allocation factor name or the exact name of an uploaded custom factor. |
| `min_bound` | Minimum exposure of the optimized portfolio. |
| `max_bound` | Maximum exposure of the optimized portfolio. |
| `min_active_bound` | Minimum optimized exposure minus optimization-benchmark exposure. |
| `max_active_bound` | Maximum optimized exposure minus optimization-benchmark exposure. |

Absolute and active bounds use the loadings' units. For allocation and binary membership factors, `0.05` means 5% absolute exposure or a 5 percentage point active difference. For a continuous score, the bounds use that score's scale.

For example, a portfolio with 65% equity exposure and an optimization benchmark with 60% equity exposure has active equity exposure of `0.05`. It meets absolute bounds of `0.50` to `0.70`, but exceeds an active maximum of `0.03`.

The active reference is the benchmark-weight portfolio supplied to the optimizer for the account. Check that reference before comparing the result with a monitoring policy, which can select a different benchmark. [Models and benchmarks](/advisor/models-and-benchmarks) explains the portfolio references used in Tilt.

## Size and capitalization buckets

Monitoring's Characteristics factor catalog labels `sze_score` as **Size**. Its presence in that catalog does not make it an accepted optimizer factor name. Custom optimizer factors require organization-configured loadings, and their scale and direction follow those supplied values.

The built-in allocation factors above do not include large-cap, mid-cap, or small-cap buckets. A custom bucket uses binary asset loadings to bound its weighted exposure; contact the Tilt team to request one. A continuous Size score measures a different quantity: a bound on its average score does not specify a percentage allocation to a capitalization bucket.

## Request a new factor

Contact the [Tilt team](mailto:contact@tilt.now) to request an additional Tilt-supplied factor or help defining custom loadings. Include:

* The exposure you want to control, such as a large-cap allocation or a Size score.
* The intended definition, units, and direction, including capitalization thresholds for a bucket.
* The asset universe and any data source or existing loadings you want to use.
* Your proposed absolute and active ranges, and the benchmark for the active comparison.

Confirm the supported factor name and loading definition with the team before configuring bounds for a requested factor.


# Customization guide
Source: https://docs.tilt.now/customization/guide

An introduction to setting up and optimizing a client portfolio.

## Overview

The Tilt Portfolio Optimization Platform enables you to create personalized portfolio optimizations for your clients. This guide walks through the complete workflow from initial organization setup to generating optimized trade proposals.

## Step 1: Organization Setup

### Configure Asset Classes

We'll start by defining the asset classes available in your organization. An asset class consists of a name, description, and a benchmark that represents it. We'll first search for available benchmark indexes, and then use that to create the asset class.

#### Search Available Benchmarks

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/benchmark_indexes/ \
  --header 'X-Api-Key: <api-key>'
```

[View API Reference →](/api-reference/endpoint/get-benchmark-indexes)

#### Create Asset Classes

Now we can create an asset class using one of our benchmarks. The example below uses `M75BNK-R`, which is the identifier for the `SPY` ETF.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/asset_classes/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "name": "US Equities",
  "description": "Example US Equities Asset Class",
  "benchmark_index_identifier": "M75BNK-R"
}'
```

[View API Reference →](/api-reference/endpoint/post-asset-class)

## Step 2. Portfolio Setup

Now that we have an asset class, let's create a portfolio which uses that asset class. We can make an example portfolio with a single allocation to US equities, although it is possible to blend multiple asset classes together.

We reference the asset class using it's UUID that was returned when creating it. We can always [list available asset classes](/api-reference/endpoint/get-asset-classes) to retrieve all asset classes.

At this point, we can enable direct indexing per asset class, for this portfolio. Later, we can override this setting per client too.

> [!TIP]
>
> Direct indexing only takes affect if the underlying benchmark index also supports direct indexing.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/portfolio_configs/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "name": "Example Portfolio",
  "asset_allocations": [
    {
      "asset_class_uuid": "asset-class-uuid",
      "target_allocation": "1",
      "direct_indexing_enabled": true
    }
  ]
}'
```

[View API Reference →](/api-reference/endpoint/post-portfolio-config)

## Step 3: Client and Account Setup

### Understanding Clients and Accounts

In Tilt, a **client** represents a person or entity in your system, and each client can have one or more **accounts**. Holdings, portfolio assignments, and optimizations all operate at the account level.

When you create a client, a default account is automatically created. The response includes both the client UUID and the account UUID within the `accounts` array.

### Create a Client

Let's create a new client, which will also create a default account. The `external_id` should be a string that represents this client in your system.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "external_id": "<string>"
}'
```

The response will include:

* `uuid`: The client UUID
* `accounts`: An array containing the default account with its own `uuid`

> [!TIP]
>
> When creating a client, we can also provide configuration and holdings information for the default account, but we'll update those separately in this guide.

[View API Reference →](/api-reference/endpoint/post-org-client)

### Update Account Holdings

Now, let's assign the account to a portfolio and update its holdings.

We use the portfolio UUID which was returned when creating the portfolio, or we can find it by [listing the available portfolios](/api-reference/endpoint/get-portfolio-configs).

```bash theme={null}
curl --request PATCH \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "portfolio_config_uuid": "portfolio-config-uuid",
    "holdings": {
      "tax_lots": [
        {"tilt_asset_id": "$USD", "quantity": "50000", "cost_basis": "1", "cost_basis_currency": "USD", "fx_rate": "1", "trade_date": "2000-01-01", "wash_sale_date": "2000-01-01", "last_sold_for_loss_date": "2000-01-01"},
        {
          "tilt_asset_id": "MH33D6-R",
          "quantity": "100",
          "cost_basis": "250",
          "trade_date": "2025-01-01",
          "wash_sale_date": "2025-01-01",
          "last_sold_for_loss_date": "2025-01-01"
        },
        {
          "tilt_asset_id": "P8R3C2-R",
          "quantity": "50",
          "cost_basis": "120",
          "trade_date": "2025-01-01",
          "wash_sale_date": "2025-01-01",
          "last_sold_for_loss_date": "2025-01-01"
        }
      ],
      "non_tradable_assets_value": "5000"
    }
  }'
```

> [!TIP]
>
> `MH33D6-R` and `P8R3C2-R` are the identifiers for Apple and Microsoft respectively. More information on asset identifiers is in the [Tilt Asset IDs](#tilt-asset-ids) section.

[View API Reference →](/api-reference/endpoint/patch-client-account)

### Update Direct Indexing Preference

We may override the direct indexing preferences for an account by updating `asset_class_settings`. For example, we can disable direct indexing for a particular asset class:

```bash theme={null}
curl --request PATCH \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "asset_class_settings": [
      {
        "asset_class_uuid": "asset-class-uuid",
        "direct_indexing_enabled": false
      }
    ]
  }'
```

[View API Reference →](/api-reference/endpoint/patch-client-account)

## Step 4: Portfolio Optimization

To constrain asset-class allocations or custom factor exposures, [configure factor exposure bounds](/customization/configure-factor-bounds) before running optimization. The [factor reference](/customization/factor-bounds) lists built-in allocation factors, custom-loading requirements, and exposure units.

We can run optimization either for a single account, or in bulk across many accounts and clients. To start with, let's run the optimization for a single account.

### Single Account Optimization

Run an optimization for an individual account to get customized portfolio weights:

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/optimize/ \
  --header 'X-Api-Key: <api-key>'
```

[View API Reference →](/api-reference/endpoint/post-account-optimize)

### Generate Trade Proposals

Convert the optimized weights into actionable trade proposals.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/clients/{client_uuid}/accounts/{account_uuid}/proposal/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "optimized_weights": {
      "MH33D6-R": "0.5",
      "P8R3C2-R": "0.5"
    }
  }'
```

[View API Reference →](/api-reference/endpoint/post-account-proposal)

## Step 5: Bulk Operations

### Bulk Optimization and Proposals

We can optimize clients in bulk by calling the bulk optimize endpoint, passing in a list of client UUIDs. This responds with a list of proposal UUID's, that we can then check the result of.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/optimized_proposals/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "client_uuids": [
      "client-uuid-1",
      "client-uuid-2",
      "client-uuid-3"
    ]
  }'
```

[View API Reference →](/api-reference/endpoint/post-bulk-client-optimize-proposal)

### Check Task Results

We can get the status for each proposal by calling the check status endpoint:

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/optimized_proposals/status/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
    "uuids": [
      "proposal-uuid-1",
      "proposal-uuid-2",
      "proposal-uuid-3"
    ]
  }'
```

[View API Reference →](/api-reference/endpoint/get-bulk-optimization-status)

To get the result for a generated proposal, we can call the get task result endpoint. This will return both the optimized weights and generated trades for that proposal.

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/optimized_proposals/{proposal_uuid}/ \
  --header 'X-Api-Key: <api-key>'
```

[View API Reference →](/api-reference/endpoint/get-optimization-task-result)

We can also search all generated proposals, and filter them based on criteria such as age, drift or turnover.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/optimized_proposals/list/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "status": "pending",
  "created_after": "2025-10-01",
  "min_average_drift": "0.1"
}'
```

[View API Reference →](/api-reference/endpoint/search-optimized-proposals)

## Configuration Hierarchy

Optimization configuration can be set on the account-level, portfolio-level, and organization level, and are merged together based on this order of precedence:

1. **Account config** (highest priority)
2. **Portfolio config**
3. **Organization config** (fallback defaults)

The configs are represented by the same schema, so all config values can be overriden at each level. The account and organization config is set in the `customization_config` field in their respective schemas.

Note that account and organization values outside of `customization_config` are unique to the account or organization, and are not merged. For example, `factor_values` is a top-level field in the organization schema. It is set globally for the organization, and cannot be overridden. Most properties are set via config however, and can be flexibly overridden as needed.

> [!NOTE]
>
> For list values (e.g., `no_trade` assets), the system uses the most specific non-empty list available. For example, if an account has any `no_trade` assets defined, these completely replace any organization-level `no_trade` assets rather than merging.

> [!TIP]
>
> You can also set **dynamic rules** on configs at any level to make parameter values change automatically based on time schedules and conditions. See the [Dynamic rules guide](/dynamic-rules/guide) for details.

## Tilt Asset IDs

We use asset IDs throughout the API to identify assets, rather than symbols. We can use the [search tickers endpoint](/api-reference/endpoint/search-tickers) to find the tilt asset ID corresponding to a certain ticker symbol.

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/tickers/search?symbols=MSFT&ticker_types=common_stock \
  --header 'X-Api-Key: <api-key>'
```


# Dynamic rules guide
Source: https://docs.tilt.now/dynamic-rules/guide

Automatically adjust optimization parameters based on time schedules and conditions.

> [!NOTE]
>
> This guide describes the API's rule format, including cron schedules and expression fields. To edit sentence-shaped rules in Tilt, follow [Set conditional rules and preview their effect](/advisor/configuration-and-rules). That guide covers account, model, and organization editors, conditional restrictions and bounds, and previewing an account draft before saving.

## Overview

Dynamic rules let you make optimization config values change automatically based on **time** (cron schedules) and **conditions** (expressions evaluated against portfolio context). Instead of manually updating configs when market conditions change or calendar events occur, you define rules that activate automatically.

Common use cases:

* Increase tax-loss harvesting aggressiveness in December
* Adjust position weight limits based on AUM
* Change optimization mode based on portfolio characteristics
* Apply different parameters for accounts meeting specific criteria

## Rule Structure

Dynamic rules are attached to a config (organization, portfolio, or account level) via the `dynamic_rules` array. Each entry targets a specific config field and contains one or more rules:

```json theme={null}
{
  "dynamic_rules": [
    {
      "field_name": "max_weight",
      "rules": [
        {
          "cron": "",
          "condition": "aum > 1000000",
          "value": 0.08,
          "priority": 0
        },
        {
          "cron": "",
          "condition": "aum > 5000000",
          "value": 0.05,
          "priority": 1
        }
      ]
    }
  ]
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `field_name` | string | Yes | Config field to set dynamically (e.g. `max_weight`, `tax_preferences.tax_gamma`) |
| `rules` | array | Yes | One or more rule entries |

### Rule Entry Fields

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `cron` | string | No | `""` | Cron expression for time-based activation (e.g. `* * * 12 *` for December) |
| `condition` | string | No | `""` | Boolean expression evaluated against context variables (e.g. `aum > 1000000`) |
| `starts_from` | date string | No | — | First trade date on which the rule can match, inclusive (`YYYY-MM-DD`) |
| `expires_at` | date string | No | — | Last trade date on which the rule can match, inclusive (`YYYY-MM-DD`) |
| `value` | any | Yes | — | Value to apply when the rule matches |
| `priority` | integer | No | `0` | Evaluation order (0-9999). Lowest number is evaluated first; first matching rule wins |

A rule matches when its supplied cron schedule, condition, and date bounds are satisfied. Empty cron and condition fields add no restriction. At least one of `cron`, `condition`, `starts_from`, or `expires_at` must be provided. If both date bounds are supplied, `starts_from` must be on or before `expires_at`.

A date-bound rule can omit both cron and condition. For example, this rule applies throughout December 2026, including both boundary dates:

```json theme={null}
{
  "field_name": "max_weight",
  "rules": [
    {
      "starts_from": "2026-12-01",
      "expires_at": "2026-12-31",
      "value": 0.05,
      "priority": 0
    }
  ]
}
```

## Rule Resolution

For each dynamic rule field (e.g. `max_weight`), the system follows a three-step resolution path:

### Step 1: Collect rules from all config levels

Rules from every config level are gathered and given a priority offset so that higher-level configs always take precedence:

| Config level | Priority offset | Precedence |
| - | - | - |
| Account rules | priority + 0 | Highest |
| Portfolio rules | priority + 10,000 | Middle |
| Org rules | priority + 20,000 | Lowest |

### Step 2: Find first static value and prune

Walk the config chain from most specific to least. The first level that sets a static value for the field becomes the default. Rules from levels **below** that level are pruned — rules at the same level still apply.

```
Account config has field?
 |
 |-- YES --> default = account value
 |           prune rules with priority >= 10,000
 |           (portfolio + org rules removed; account rules survive)
 |
 NO
 |
 v
Portfolio config has field?
 |
 |-- YES --> default = portfolio value
 |           prune rules with priority >= 20,000
 |           (org rules removed; account + portfolio rules survive)
 |
 NO
 |
 v
Org config has field?
 |
 |-- YES --> default = org value
 |           no pruning needed (nothing below org)
 |           (all rules survive)
 |
 NO
 |
 v
default = None (no static value anywhere, no rules pruned)
```

### Step 3: Evaluate remaining rules

Remaining rules are sorted by priority ascending. **First matching rule wins** — the first rule whose supplied cron, condition, and date bounds are satisfied is used. If no rule matches, the default value from step 2 is used.

**Key concepts:**

* **Priority offsets**: Account rules keep their raw priority, portfolio rules add 10,000, and org rules add 20,000. This means account-level rules are always evaluated before lower levels.
* **Static value pruning**: When a static value is found at a config level, rules from levels below are pruned. Rules at the same level as the static value still apply. This prevents lower-level dynamic rules from overriding an explicit static value set at a higher level.
* **First match wins**: Rules are evaluated in ascending priority order. The first rule whose supplied cron, condition, and date bounds match is used.
* **Fallback**: If no rule matches, the static default value from step 2 is used.

## Supported Fields

### Config Fields

Dynamic rules can target the fields returned by the schema endpoint, including:

* `max_weight`, `min_weight` — position weight limits
* `optimization_mode` — optimization strategy
* `cash_buffer_usd`, `cash_buffer_cad` — cash reserves as fractions of portfolio value
* `cash_buffer_usd_amount`, `cash_buffer_cad_amount` — fixed cash reserves in the named currency
* `require_whole_shares` — whole-share trading requirement

### Tax Preference Fields

Use the `tax_preferences.` prefix for tax preference fields:

* `tax_preferences.tax_gamma`
* `tax_preferences.short_term_rate`
* `tax_preferences.long_term_rate`

> [!TIP]
>
> Use the [Get Dynamic Rules Schema](/api-reference/endpoint/get-dynamic-rules-schema) endpoint to discover all supported fields, available context variables, functions, and operators for your organization.

## Context Variables

Conditions in dynamic rules are evaluated against context variables that describe the portfolio and account at optimization time.

### Portfolio-Level Variables

Variables like `aum`, `cash_balance`, and `position_count` describe the current state of the portfolio being optimized.

### Account-Level Variables

Variables like `organization_name` and `client_external_id` describe the account and organization.

### Fundamental Per-Ticker Variables

Variables like `market_cap` and `pe_ratio` provide fundamental data for individual securities. These are available when rules are evaluated at the ticker level.

### Enrichment Columns

Custom enrichment data columns uploaded to your organization are also available as context variables.

> [!NOTE]
>
> The exact set of available variables depends on your organization's configuration. Use the schema endpoint to discover what's available.

## Workflow

### Step 1: Explore the Schema

Discover available fields, variables, operators, and functions:

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/schema/ \
  --header 'X-Api-Key: <api-key>'
```

[View API Reference →](/api-reference/endpoint/get-dynamic-rules-schema)

The response includes:

* **fields**: Config fields that support dynamic rules
* **variables**: Context variables available in conditions
* **functions**: Functions you can use in expressions (e.g. `abs()`, `max()`)
* **operators**: Supported operators (`>`, `<`, `==`, `and`, `or`, etc.)
* **examples**: Example expressions

### Step 2: Validate Expressions

Before deploying rules, validate that your condition expressions are syntactically correct:

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/validate/ \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "expression": "aum > 1000000 and position_count < 50"
  }'
```

[View API Reference →](/api-reference/endpoint/post-dynamic-rules-validate)

You can also pass a `sample_context` to test evaluation:

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/validate/ \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "expression": "aum > 1000000",
    "sample_context": {"aum": 2000000}
  }'
```

### Step 3: Attach Rules to a Config

Add dynamic rules when creating or updating a config at any level. For example, to add rules to a portfolio config:

```bash theme={null}
curl --request PATCH \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/portfolio_configs/{config_uuid}/ \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customization_config": {
      "dynamic_rules": [
        {
          "field_name": "max_weight",
          "rules": [
            {
              "condition": "aum > 1000000",
              "value": 0.08,
              "priority": 0
            }
          ]
        }
      ]
    }
  }'
```

### Step 4: Simulate Rule Evaluation

Test how rules resolve for a specific account and date without running an optimization:

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/simulate/ \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_account_uuid": "account-uuid-here",
    "trade_date": "2025-12-15"
  }'
```

[View API Reference →](/api-reference/endpoint/post-dynamic-rules-simulate)

The response shows:

* **resolved\_values**: The final config values after rule evaluation
* **context**: The context variables used during evaluation
* **rule\_evaluations**: Which rules matched and which didn't, with details

You can also pass `dynamic_rules` directly to simulate rules that haven't been saved yet.

### Step 5: Preview Optimization Impact

See how dynamic rules affect actual optimization results by comparing scenarios. Preview runs asynchronously — you submit a job, then poll for results.

#### Submit a preview job

POST your scenarios to create a preview job. Each scenario requires a `label` and `context_overrides` (e.g. to vary `aum` or `trade_date`). You can optionally include `as_of_datetime`, `fundamentals_overrides`, and `config_overrides`.

```bash theme={null}
curl --request POST \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/ \
  --header 'X-Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_account_uuid": "account-uuid-here",
    "scenarios": [
      {
        "label": "Summer baseline",
        "context_overrides": {"trade_date": "2025-06-15"}
      },
      {
        "label": "Year-end TLH",
        "context_overrides": {"trade_date": "2025-12-15"}
      }
    ],
    "include_baseline": true
  }'
```

The endpoint returns `202 Accepted` with a job object:

```json theme={null}
{
  "id": "job-uuid",
  "status": "PENDING",
  "params": { ... },
  "result": null,
  "error_message": null,
  "created_at": "2025-06-01T12:00:00Z",
  "started_at": null,
  "finished_at": null
}
```

[View API Reference →](/api-reference/endpoint/post-dynamic-rules-preview)

#### Poll for results

Use the job ID to check status and retrieve results:

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/{job_id}/ \
  --header 'X-Api-Key: <api-key>'
```

| Status | Meaning |
| - | - |
| `PENDING` | Job is queued |
| `RUNNING` | Optimization is in progress |
| `SUCCESS` | Results are available in the `result` field |
| `FAILURE` | Job failed — check `error_message` for details |

> [!TIP]
>
> Poll every 2–5 seconds. Most preview jobs complete within 30 seconds.

[View API Reference →](/api-reference/endpoint/get-dynamic-rules-preview-job)

#### List previous jobs

Browse your organization's preview job history:

```bash theme={null}
curl --request GET \
  --url https://api.tilt.now/api/v1/custom/org/{organization_uuid}/dynamic_rules/preview/jobs/ \
  --header 'X-Api-Key: <api-key>'
```

[View API Reference →](/api-reference/endpoint/list-dynamic-rules-preview-jobs)

## Examples

### Year-End Tax-Loss Harvesting

Increase the tax-loss harvesting aggressiveness during December:

```json theme={null}
{
  "dynamic_rules": [
    {
      "field_name": "tax_preferences.tax_gamma",
      "rules": [
        {
          "cron": "* * * 12 *",
          "value": 5.0,
          "priority": 0
        }
      ]
    }
  ]
}
```

**Resolution in December (e.g. trade date 2025-12-15):**

```
Rule priority 0: cron "* * * 12 *" → matches → value = 5.0 ✓ MATCH
                                                ────────
                                      Result:   tax_gamma = 5.0
```

**Resolution outside December (e.g. trade date 2025-06-15):**

```
Rule priority 0: cron "* * * 12 *" → does not match → skipped
                 No rules matched → use default from static config
```

### AUM-Based Weight Limits

Tighten position concentration limits for larger portfolios:

```json theme={null}
{
  "dynamic_rules": [
    {
      "field_name": "max_weight",
      "rules": [
        {
          "condition": "aum > 1000000",
          "value": 0.08,
          "priority": 0
        },
        {
          "condition": "aum > 5000000",
          "value": 0.05,
          "priority": 1
        }
      ]
    }
  ]
}
```

**Resolution for a portfolio with 2M AUM:**

```
Rule priority 0: condition "aum > 1000000" → true  → value = 0.08 ✓ MATCH
                                                     ────────
                                           Result:   max_weight = 0.08
```

**Resolution for a portfolio with 10M AUM:**

```
Rule priority 0: condition "aum > 1000000" → true → value = 0.08 ✓ MATCH
                                                    ────────
                                          Result:   max_weight = 0.08
```

Both portfolios match the first rule. If you want different behavior for larger portfolios, put the more specific condition at a lower priority number so it matches first:

```json theme={null}
{
  "dynamic_rules": [
    {
      "field_name": "max_weight",
      "rules": [
        {
          "condition": "aum > 5000000",
          "value": 0.05,
          "priority": 0
        },
        {
          "condition": "aum > 1000000",
          "value": 0.08,
          "priority": 1
        }
      ]
    }
  ]
}
```

Now a 10M AUM portfolio matches priority 0 first and gets `0.05`, while a 2M AUM portfolio skips priority 0 and matches priority 1 for `0.08`.

### Multi-Level Rules with Static Value Pruning

This example shows how rules accumulate across config levels and how a static value prunes lower-level rules.

**Config state for `max_weight`:**

```
Account:    rule {cron: Dec → 0.50, priority: 1}   max_weight = NULL
Portfolio:  rule {always → 0.06, priority: 1}       max_weight = 0.05
Org:        rule {always → 0.03, priority: 1}       max_weight = NULL
```

**Step 1 — Collect and offset rules:**

```
Account rule:   {cron: Dec, value: 0.50, priority: 1 + 0     = 1}
Portfolio rule: {always,     value: 0.06, priority: 1 + 10000 = 10001}
Org rule:       {always,     value: 0.03, priority: 1 + 20000 = 20001}
```

**Step 2 — Find static value and prune:**

```
Account config  → max_weight = NULL → skip
Portfolio config → max_weight = 0.05 → default = 0.05
                   Prune rules with priority ≥ 20,000
                   ├── Portfolio rule (pri 10001) → KEPT
                   └── Org rule       (pri 20001) → PRUNED

Remaining rules: [{cron: Dec, value: 0.50, priority: 1},
                  {always, value: 0.06, priority: 10001}]
Default value:   0.05
```

**Step 3 — Evaluate remaining rules:**

**In December:**

```
Rule priority 1: cron "Dec" → matches → value = 0.50 ✓ MATCH
                                         ────────
                               Result:   max_weight = 0.50
```

**In June:**

```
Rule priority 1:     cron "Dec" → does not match → skipped
Rule priority 10001: always → matches → value = 0.06 ✓ MATCH
                                      ────────
                            Result:   max_weight = 0.06 (portfolio rule)
```

The portfolio's static `max_weight = 0.05` becomes the fallback default and prunes the org-level dynamic rule. Account-level and portfolio-level rules survive. The portfolio's always-matching rule supplies `0.06` when the account's December rule does not match; the static default is used only if no surviving rule matches.

## Best Practices

* **Simulate before deploying** — Always use the simulate endpoint to verify rule behavior before saving rules to a config. Check that the right rules match and produce expected values.
* **Start priorities at 0** — Use sequential integers starting from 0 (0, 1, 2, ...). You can leave gaps if you anticipate inserting rules later.
* **Understand static blocking** — Be intentional about static values at higher config levels, as they suppress dynamic rules from lower levels for that field.
* **Use the schema endpoint** — Discover available fields and variables programmatically rather than hardcoding. The available set may expand over time.
* **Keep conditions simple** — Prefer clear, readable expressions. Use the validate endpoint to catch syntax errors early.

***

Wash-sale rules may disallow a loss if substantially identical securities are bought within 30 days before or after the sale, including in the client’s other accounts, such as IRAs or a spouse’s accounts. The Platform’s wash-sale checks cover only accounts on the Platform, so confirm the client’s full position with a qualified tax professional.

See [IRS Publication 550](https://www.irs.gov/publications/p550) for U.S. wash-sale rules.


# Build and backtest a Tilt
Source: https://docs.tilt.now/index-construction/api-guide

Use the REST API to discover construction fields, create a Tilt, evaluate it, read its constituents, and run a backtest.

This guide builds a quarterly quality-growth Tilt from catalog discovery through
backtesting. It uses one Tilt throughout so that each response supplies the IDs
and revision needed by the next request.

These endpoints are part of the [index construction REST API design
preview](/index-construction/api-preview) and are not available.

Set the base URL and API key used by the examples:

```bash theme={null}
export TILT_API_URL="https://x.invalid"
export TILT_API_KEY="YOUR_API_KEY"
```

## Step 1: Discover fields and a universe

Construction expressions use exact catalog field names. List the catalog to
browse every base field and constructed signal:

```bash theme={null}
curl --request GET \
  --url "$TILT_API_URL/api/v1/catalog" \
  --header "X-Api-Key: $TILT_API_KEY"
```

The response groups fields into `base_columns` and `constructed_signals` and
includes their descriptions, examples, types, and units when available.
Constructed signals also include their equations. The optional
`aggregation_functions` block describes the trailing-window functions accepted
by construction expressions.

Search the catalog when you know the concept but need its exact field name:

```bash theme={null}
curl --request POST \
  --url "$TILT_API_URL/api/v1/catalog/search" \
  --header "X-Api-Key: $TILT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "operating margin",
    "limit": 10
  }'
```

Use the returned `name` in an expression. Inspect an exact field to check its
units, coverage, null rate, and distribution before choosing a threshold:

```bash theme={null}
curl --request POST \
  --url "$TILT_API_URL/api/v1/catalog/inspect" \
  --header "X-Api-Key: $TILT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"column_name":"market_cap"}'
```

Universe preset IDs are discovered rather than fixed in the API schema:

```bash theme={null}
curl --request GET \
  --url "$TILT_API_URL/api/v1/catalog/universe_presets" \
  --header "X-Api-Key: $TILT_API_KEY"
```

Choose the `id` that describes the intended candidate universe. A named index
is not a universe preset; use an expression such as `index("S&P 500") > 0` in
the filter when index membership is part of the methodology.

[List catalog reference →](/api-reference/index-construction-preview/list-catalog) · [Search catalog reference →](/api-reference/index-construction-preview/search-catalog)

## Step 2: Create the Tilt project

Create an unevaluated draft. This establishes the Tilt project and its first
version but does not produce constituents yet.

```bash theme={null}
curl --request POST \
  --url "$TILT_API_URL/api/v1/tilts" \
  --header "X-Api-Key: $TILT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Quality Growth",
    "universe_preset": "us_investable"
  }'
```

The response contains two identities:

```json theme={null}
{
  "uuid": "6bcfd210-80f5-4f0b-ab27-6b675194a4a1",
  "version_group_sqid": "quality-growth",
  "revision": "2026-09-29T14:32:10Z",
  "name": "Quality Growth",
  "universe_preset": "us_investable"
}
```

* `version_group_sqid` identifies the Tilt project across its versions.
* `uuid` identifies this particular draft or published version.
* `revision` is the optimistic-concurrency token for the next edit.

Save the returned UUID for the remaining requests:

```bash theme={null}
export TILT_UUID="6bcfd210-80f5-4f0b-ab27-6b675194a4a1"
```

[Create a Tilt reference →](/api-reference/index-construction-preview/create-tilt)

## Step 3: Resolve any ticker overrides

Skip this step when the methodology has no forced inclusions or exclusions.
Overrides require exact `tilt_asset_id` values, not ticker symbols:

```bash theme={null}
curl --request GET \
  --get \
  --url "$TILT_API_URL/api/v1/tickers/search" \
  --data-urlencode "symbols=AAPL" \
  --data-urlencode "exchange=XNAS" \
  --header "X-Api-Key: $TILT_API_KEY"
```

A symbol can identify more than one listing. Compare the returned name,
exchange, and security type before selecting the intended `tilt_asset_id`.

[Resolve ticker listings reference →](/api-reference/index-construction-preview/search-tickers)

## Step 4: Save and evaluate the methodology

Apply construction rules to the draft. This operation saves the effective
methodology and its complete weighted constituent snapshot together. If
validation or evaluation fails, it saves neither.

```bash theme={null}
curl --request PATCH \
  --url "$TILT_API_URL/api/v1/tilts/$TILT_UUID" \
  --header "X-Api-Key: $TILT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "base_revision": "2026-09-29T14:32:10Z",
    "assignment_expression": "quality=revenue_growth_3y+roe",
    "filter_expression": "market_cap>5000 and fcf_margin>0.08",
    "score_expression": "quality",
    "weight_expression": "free_float_market_cap",
    "included_tilt_asset_ids": [],
    "excluded_tilt_asset_ids": [],
    "rules": {
      "max_constituents": 20,
      "rebalancing_period": "QUARTERLY",
      "capping_methodology": "THRESHOLD_BASED",
      "max_position_weight": "0.10",
      "top_n_position_threshold": "0.045",
      "top_n_position_weight": "0.45"
    }
  }'
```

The response includes the effective rules and an evaluation summary. Keep its
`tilt_uuid` and `revision`: applying changes to a published Tilt can create a
new draft UUID, so the response is authoritative for subsequent requests.

> [!NOTE]
>
> `rebalancing_period` is part of the saved methodology. It accepts `MONTHLY`,
> `QUARTERLY`, `SEMI_ANNUALLY`, or `ANNUALLY`. The backtest endpoint follows
> this value; it does not accept a separate cadence override.

[Apply construction reference →](/api-reference/index-construction-preview/apply-construction)

## Step 5: Read the evaluated constituents

Read the complete stored result after a successful apply:

```bash theme={null}
curl --request GET \
  --url "$TILT_API_URL/api/v1/tilts/$TILT_UUID/constituents" \
  --header "X-Api-Key: $TILT_API_KEY"
```

```json theme={null}
{
  "tilt_uuid": "6bcfd210-80f5-4f0b-ab27-6b675194a4a1",
  "revision": "2026-09-29T14:33:02Z",
  "as_of_date": "2026-09-26",
  "total_constituents": 2,
  "total_weight": 1,
  "constituents": [
    {
      "tilt_asset_id": "US0378331005-XNAS",
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "exchange": "XNAS",
      "score": 1.42,
      "weight": 0.54
    },
    {
      "tilt_asset_id": "US5949181045-XNAS",
      "symbol": "MSFT",
      "name": "Microsoft Corp.",
      "exchange": "XNAS",
      "score": 1.18,
      "weight": 0.46
    }
  ]
}
```

`weight` is a portfolio fraction, so `0.54` means 54%. This endpoint returns
the saved evaluation; reading it does not rerun the rules with newer data.

[Constituents reference →](/api-reference/index-construction-preview/get-constituents)

## Step 6: Backtest the saved methodology

Choose the analysis window with dates. Add a benchmark when you need relative
performance and risk statistics:

```bash theme={null}
curl --request GET \
  --get \
  --url "$TILT_API_URL/api/v1/tilts/$TILT_UUID/backtest" \
  --data-urlencode "start_date=2021-01-01" \
  --data-urlencode "end_date=2026-01-01" \
  --data-urlencode "benchmark=SPY" \
  --header "X-Api-Key: $TILT_API_KEY"
```

This quarterly Tilt is reconstituted quarterly throughout the requested date
range because its saved `rules.rebalancing_period` is `QUARTERLY`. To test a
monthly methodology, save a version with `MONTHLY` and backtest the UUID
returned by that apply operation. A run-time cadence override would test rules
that are not the saved methodology, so the endpoint does not allow one.

The response contains the Tilt return series and scheduled membership changes.
When `benchmark` is supplied, it also contains the benchmark series, period
returns, relative return when the coverage windows match, and risk statistics.
Rebalance events describe scheduled additions and removals; they are not a
transaction ledger or complete corporate-action history.

[Backtest reference →](/api-reference/index-construction-preview/backtest-tilt)

## Update and rerun

Read the latest Tilt before editing, then send its `revision` as
`base_revision`. Omitted construction fields keep their saved values. For
example, this changes only the cadence and reevaluates the Tilt:

```bash theme={null}
curl --request PATCH \
  --url "$TILT_API_URL/api/v1/tilts/$TILT_UUID" \
  --header "X-Api-Key: $TILT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "base_revision": "2026-09-29T14:33:02Z",
    "rules": {
      "rebalancing_period": "MONTHLY"
    }
  }'
```

Use the new `tilt_uuid` and `revision` from the response for the next
constituent read or backtest.


# API overview
Source: https://docs.tilt.now/index-construction/api-preview

The REST resources for building, evaluating, and backtesting rules-based equity Tilts.

> [!WARNING]
>
> This is a design preview. The endpoints in this section are not available.
> The reference exists to review the proposed contract before implementation.

The API exposes the same rules-based equity construction model used by Tilt
today, with a deliberately small public surface.

This proposed API accepts structured construction rules and does not put Tilt
Agent in the loop. To add natural-language construction to an application you
operate, [delegate to Tilt Agent over MCP](/tilt-agent/connect-over-mcp).

## Core model

A Tilt is a persistent project for one index methodology. Its construction
rules describe how to select and weight securities, and each successful
evaluation saves the constituents and weights those rules produced.

For developers, a bounded analogy is a GitHub repository: construction rules
are source, evaluated constituent snapshots are build artifacts, and
methodology history is version history. The analogy does not imply branches,
forks, merges, or cloning. Evaluating a Tilt does not publish an index.

The existing `version_group_sqid` identifies the project across versions. A
`uuid` addresses one particular draft or published version.

## Workflow

1. Browse the construction catalog or search it by concept, then inspect exact
   fields before choosing thresholds.
2. List universe presets and create an unevaluated draft Tilt.
3. Resolve ticker overrides to exact `tilt_asset_id` values.
4. Apply the methodology. Tilt saves the rules, evaluates them, and commits the
   complete weighted constituent snapshot atomically.
5. Read the saved constituents or backtest the saved Tilt.

Applying construction is the evaluation operation. A separate evaluation
endpoint and named-index membership endpoint are outside the initial API scope.

## Scope

The preview includes the documented rules-based equity pipeline: universe,
derived fields, selection, sizing, ticker overrides, rebalance cadence,
concentration limits, complete weighted constituents, and synchronous
backtesting.

It excludes natural-language construction, research, enrichment creation,
discretionary and event-contract Tilts, publication, and governance.

> [card] [Build and backtest a Tilt](/index-construction/api-guide)
>
> Follow the complete API workflow with requests and responses.

> [card] [Delegate to Tilt Agent from your application](/tilt-agent/connect-over-mcp)
>
> Delegate natural-language investment tasks from an application you operate.

> [card] [Create a Tilt](/api-reference/index-construction-preview/create-tilt)
>
> Create an unevaluated rules-based equity draft.

> [card] [Apply construction](/api-reference/index-construction-preview/apply-construction)
>
> Save and evaluate the construction methodology.

> [card] [Get constituents](/api-reference/index-construction-preview/get-constituents)
>
> Read the complete saved result with scores and weights.

> [card] [List the catalog](/api-reference/index-construction-preview/list-catalog)
>
> Browse every field and supported trailing-window capability.

> [card] [Search the catalog](/api-reference/index-construction-preview/search-catalog)
>
> Find fields by name or concept.


# Choose an integration
Source: https://docs.tilt.now/index-construction/choose-an-integration

Compare Tilt's built-in experience, Tilt Agent over MCP, and the index construction REST API design preview.

Choose an integration based on who owns the interface and whether the input is
a natural-language outcome or structured construction rules.

| | Tilt | Tilt Agent over MCP | REST API design preview |
| - | - | - | - |
| Availability | Available | Available for authorized Tilt users | Not available |
| Interface owner | Tilt | Your application | Your application |
| Input | Chat and editable construction rules | A complete natural-language task, with optional Tilt context | Proposed structured requests |
| Orchestration | Tilt manages the conversation and construction workflow | Tilt Agent executes the task; your application manages submission, progress, results, and follow-ups | Your application would coordinate each proposed API operation |
| State and iteration | Tilt chats and saved Tilts | A durable Tilt Agent session with one run for each turn | Proposed Tilt IDs and revisions |
| Presentation | Tilt's built-in views | Your host's model or Tilt's MCP App | Your interface |
| Best fit | Use the complete Tilt experience | Add Tilt Agent to a chat or agent you operate | Review a deterministic construction API contract |

## Use Tilt directly

Use Tilt when users can work in Tilt's chat and Tilt view. Tilt Agent can
create or refine a Tilt from a description, while the Methodology and Portfolio
tabs expose the resulting rules, constituents, and backtest.

The [thematic Tilt guide](/index-construction/example-nuclear-energy) follows
this workflow from the first request through a rule change.

## Delegate to Tilt Agent over MCP

Use MCP when your application owns the chat or agent experience and should
delegate investment work to Tilt Agent. Your host sends one complete task, such
as creating a rules-based nuclear energy Tilt, rather than translating the task
into a sequence of construction API calls.

Delegation is asynchronous. The first tool call returns a run ID and a durable
session ID. Your host reads progress and structured output from the run, then
reuses the session ID for follow-up turns. Tilt Agent can research, ask for
missing input, and use the same construction capabilities available in Tilt.

A model-driven MCP host can interpret the structured output and answer through
its native interface. For a full interactive renderer, use Tilt's MCP App; Tilt
can also customize that experience for a third-party integration. Tilt is
exploring additional custom rendering options. Contact Tilt to discuss a
specific integration.

The standard connection is authorized by a Tilt user account and currently
runs in that user's personal Tilt organization. Each host user needs a separate
authorized connection. Custom identity, organization, or single sign-on
arrangements are outside the standard connection flow.

MCP delegates complete tasks to Tilt Agent. The REST design preview accepts
individual structured operations. A delegated run can return clarification or
explanatory output as well as saved work. Index publication remains a separate
review process after Tilt creation or changes.

> [card] [Delegate to Tilt Agent from your application](/tilt-agent/connect-over-mcp)
>
> Authorize a connection, delegate a task, consume its result, and continue the
> same Tilt Agent session.

## Review the REST API design

The REST design preview describes proposed resources for clients that already
have structured construction rules and want deterministic create, apply,
constituent, and backtest operations. It excludes natural-language construction
and Tilt Agent does not participate in the workflow.

The endpoints are not available. Use the preview to evaluate the proposed
contract, not to build a production integration.

> [card] [Index construction REST API preview](/index-construction/api-preview)
>
> Review the proposed resources and workflow.


# Build a thematic Tilt
Source: https://docs.tilt.now/index-construction/example-nuclear-energy

Create a nuclear energy Tilt with Tilt Agent, read its construction rules, and refine them.

This guide builds a nuclear energy Tilt in two messages to Tilt Agent. The Tilt selects and weights companies by their exposure to a theme, so it uses `theme()` in both the filter and the score.

## 1. Ask for the Tilt

![A message asking Tilt to create a new Tilt for nuclear energy, and Tilt Agent's reply that it created Nuclear Energy Exposure with 25 companies](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/nuclear-transcript-create.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=cdfda345e5b65ee1da7aa4a6ab3c9cae)

Name the theme, the number of holdings, the weighting, the cap, and the rebalance schedule. Start with **Create a new Tilt** to get a saved Tilt you can edit, backtest, and rebalance. A request to build or research an idea returns a preview basket instead.

Tilt Agent wrote these rules:

| Rule | Value |
| - | - |
| Universe | US All Equities |
| Filter expression | `theme("Nuclear Energy") >= 0.55` |
| Score expression | `theme("Nuclear Energy")` |
| Maximum constituents | `25` |
| Weight expression | Blank, so Tilt sizes by score |
| Index cadence | Quarterly |
| Concentration | Single-position maximum 10% |

The filter keeps companies with meaningful nuclear exposure. The score ranks them by that exposure, and the Tilt holds the top 25. With the weight expression blank, each position is proportional to its exposure, and no position can exceed 10%.

## 2. Refine the rules

The first version held some companies worth a few hundred million dollars. Ask for a size floor:

![A message saying some holdings are tiny and asking to include only companies worth at least \$1 billion, and Tilt Agent's reply that it updated the Tilt](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/nuclear-transcript-refine.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=e848aaa02dbe9fd59b2e3948bf2cb19a)

Tilt Agent adds a market-cap test to the filter and leaves the other rules as they were:

![Selection rules with filter expression (theme("Nuclear Energy") >= 0.55) & (market\_cap >= 1000), score expression theme("Nuclear Energy"), and maximum constituents 25](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/nuclear-selection-rules.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=19f0e03ed9f79233fc934e3dda16fe25)

`market_cap >= 1000` means at least \$1 billion, since `market_cap` is in millions of US dollars.

Tilt records the change in the Tilt's **History**, alongside the original rules.

To make the same change by hand, open **Selection rules** and edit the filter expression. Then open the change queue at the bottom of the Tilt view and select **Apply**. The **Theme importance** control in that section sets how much each theme counts in the score. Tilt drafts the new score expression for you to review before it applies.

## 3. Review the result

The **Methodology** tab shows a backtest against a benchmark and every rule by section:

![The Methodology tab for Nuclear Energy Exposure, with a one-year backtest against SPY, risk statistics, and the methodology sections](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/nuclear-methodology-tab.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=33bb925c7ccdf7c757ff39df21939752)

The **Portfolio** tab lists each constituent's exposure, sector, market cap, and weight:

![The Portfolio tab listing 25 holdings, including Duke Energy, Energy Fuels, PG\&E, and Cameco, with score, market cap, sector, and weight](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/nuclear-portfolio-tab.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=da5ad8fbd557f4b2a8d62546839e70f7)

Each quarter, Tilt reruns the rules on fresh data. Companies that gain nuclear exposure can enter the Tilt, and companies that lose it drop out.

## Variations

| Goal | Change |
| - | - |
| Start from an existing index's members | Add `index("S&P 500") > 0` to the filter. |
| Require consistent profits | Add `min(operating_income, "3y") > 0` to the filter. |
| Blend two themes | Score with `theme("Nuclear Energy") + 0.5 * theme("Grid Modernization")`. |
| Exclude a theme | Add `theme("Fossil Fuels") < 0.55` to the filter. |

[How theme() scores companies](/index-construction/expressions#how-theme-scores-companies) explains where exposure scores come from.


# Expression reference
Source: https://docs.tilt.now/index-construction/expressions

Fields, operators, and functions for derived fields, filter, score, and weight expressions.

Construction rules are expressions. Tilt evaluates each expression once per security in the universe, as of the evaluation date. The syntax is Python-style arithmetic and comparison over named fields.

## Expression types

| Expression | Editor section | Result per security | Use |
| - | - | - | - |
| Assignment | Derived fields | Named values | Defines names for later expressions. |
| Filter | Selection rules | True or false | Keeps securities where the result is true. |
| Score | Selection rules | A number | Ranks securities, highest first. |
| Weight | Position sizing | A number | Sets relative position size. Tilt scales weights to sum to 100%. |

![Selection rules section with filter expression market\_cap > 5000 and fcf\_margin > 0.08, score expression 2 \* revenue\_growth\_3y + roe, and maximum constituents 20](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-selection-rules.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=7f85d992265cff7aa411527f2e829f70)

Filter and score expressions in the Selection rules section. Tilt highlights field names.

## Fields

A field is a named value for each security, such as `market_cap`, `pe`, or `roe`. The field catalog covers fundamentals, valuation, returns, liquidity, classification, and risk-model factor exposures. Tilt Agent can search the catalog for a field's exact name and show its distribution.

| Convention | Detail | Example |
| - | - | - |
| Units | Each field has a unit in the catalog. `market_cap` is in millions of US dollars. | `market_cap > 5000` keeps companies worth more than \$5 billion. |
| Risk-model factors | Standardized exposures with the `rm_` prefix. 0 is close to the market average. | `rm_momentum`, `rm_value`, `rm_quality`, `rm_volatility`, `rm_historical_beta` |
| Classification | RBICS levels: `rbics_l1_id` for sector, `rbics_l2_id` for subsector, `rbics_l3_id` for industry. | `rbics_l3_id == 551020` selects Semiconductor Manufacturing. |

## Operators

| Kind | Operators | Example |
| - | - | - |
| Arithmetic | `+` `-` `*` `/` `**` | `2 * revenue_growth_3y + roe` |
| Comparison | `>` `>=` `<` `<=` `==` `!=` | `pe < 25` |
| Logic | `and` `or` `not`, or `&` `\|` `~` | `market_cap > 5000 and fcf_margin > 0.08` |
| Grouping | `( )` | `(pe < 25) & (market_cap > 1000)` |

Wrap each comparison in parentheses when you combine comparisons with `&` or `|`.

## Derived fields

An assignment expression names a value for reuse. Write one assignment per line:

```python theme={null}
quality = 2 * revenue_growth_3y + roe
size_basis = free_float_market_cap
```

Filter, score, and weight expressions can then use `quality` and `size_basis` like any other field. Tilt evaluates derived fields first.

![Derived fields section with two assignments: quality and size\_basis](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-derived-fields.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=a5e784761fae1ce4e0ac022b95b55c05)

## Functions

### Membership and exposure

These functions look up a value by name. They work in filter and score expressions only. A derived field or weight expression that calls one fails.

| Function | Returns | Example |
| - | - | - |
| `index("<name>")` | The security's point-in-time weight in a named index, or 0 | `index("S&P 500") > 0` |
| `etf("<ticker>")` | The security's point-in-time weight in an ETF's holdings, or 0 | `etf("QQQ") > 0` |
| `theme("<label>")` | The company's exposure to a theme, or 0 with no evidence | `theme("Nuclear Energy") >= 0.55` |
| `feature("<id>")` | A custom numeric feature shared with your organization | `feature("momentum_composite") > 0.5` |
| `enrichment("<id>")` | A custom AI-scored column you created | `enrichment("moat_score") > 7` |

`index()` accepts published Tilt index names and third-party index names. A third-party name resolves to the holdings of the largest ETF that tracks the index. Universe presets are a separate setting, in the Universe section.

`theme()` takes a theme in plain language, such as `"Nuclear Energy"` or `"Grid Modernization"`:

| Use | Expression |
| - | - |
| Include exposed companies | `theme("Nuclear Energy") >= 0.55` in the filter |
| Exclude exposed companies | `theme("Fossil Fuels") < 0.55` in the filter |
| Rank and size by exposure | `theme("Nuclear Energy")` as the score, with no weight expression |

The score starts at 0 and has no fixed maximum. Companies with heavy exposure often score several points. Tilt's default cutoff is 0.55, and Tilt Agent uses it unless you name another threshold. Every share class of a company gets the same score. [Build a thematic Tilt](/index-construction/example-nuclear-energy) walks through a Tilt built with `theme()`.

### How theme() scores companies

Tilt matches the theme against several kinds of evidence for each company, including its SEC filings, financial news coverage, earnings calls, and analyst research. Tilt weights each source by how well it predicted relevance in testing, then combines them into one score. Every piece of evidence has a date, so a backtest sees only the evidence available on each historical date.

The [thematic scoring white paper](https://tilt.io/research/tilt-research-engine-whitepaper.pdf) documents the method, its sources, and its validation. Across 81 themes, companies it selected on held-out data averaged 8.36 out of 10 for relevance, as judged by a relevance grader that a blinded panel of portfolio managers and analysts validated.

Coverage is strongest for US-listed companies, since much of the evidence comes from SEC filings and English-language financial news. A company that has changed its business keeps its old filing description until its next annual report.

### Trailing-window statistics

These functions summarize a field over a window that ends on the evaluation date. They work in all four expression types.

| Function | Returns | Example |
| - | - | - |
| `avg(field, "window")` | Mean | `avg(pe, "3m") > 20` |
| `median(field, "window")` | Median | `median(quick_ratio, "1y") > 1.5` |
| `min(field, "window")` | Lowest value | `min(operating_income, "3y") > 0` |
| `max(field, "window")` | Highest value | `market_cap / max(market_cap, "1y")` |
| `std(field, "window")` | Standard deviation | `std(gross_margin, "1y") < 0.05` |
| `first(field, "window")` | Value at the start of the window | `revenue > first(revenue, "1y")` |

Write the field as a bare name and the window as a quoted string, such as `"3m"`, `"1y"`, or `"5y"`. Daily fields such as `market_cap` and `pe` support short windows. Quarterly fundamentals such as `revenue` update four times a year, so use windows of one year or more. `first()` accepts quarterly fundamentals only. The catalog lists the windows each field accepts.

## Validation

Tilt checks expressions as you type. An unknown field name shows an error below the expression, with the closest catalog field when one matches. Fix the error before you select **Apply** in the change queue.

![Filter expression market\_cap > unknown\_metric with the error: Unknown field 'unknown\_metric'](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-validation-error.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=d338efac04de21d5261cd394b25e7a30)


# Index construction
Source: https://docs.tilt.now/index-construction/overview

How a Tilt turns construction rules into a rules-based portfolio: universe, selection, sizing, and rebalancing.

A Tilt is a rules-based portfolio: a set of construction rules and the constituents they produce. Tilt applies the rules to a universe of securities, ranks the securities that pass, sizes the positions, and returns the constituents. Each rebalance runs the same rules on fresh data.

You can write the rules yourself or describe the Tilt to Tilt Agent, which writes them for you. You can read and edit every rule either way.

Marketplace publishing creates a public version of a Tilt. **Submit as an Index** starts a separate index-submission review. Read [working copies and published versions](/index-construction/working-copies-and-published-versions) for version labels, Marketplace listing, and sleeve use.

## The construction pipeline

![The construction pipeline: universe, derived fields, selection rules, position sizing, ticker overrides, rebalance and concentration, constituents](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/pipeline.svg?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=9cd71bc010cd3b0a9061ed032d1d2cd7)

Each stage is a section on a Tilt's **Methodology** tab:

| Stage | What it does | Index-methodology term |
| - | - | - |
| Universe | Sets the eligible starting securities, such as US-listed investable equities. | Parent index or eligible universe |
| Derived fields | Names values for later stages to reuse, such as a quality composite. | Factor definitions |
| Selection rules | The filter expression removes ineligible securities. The score expression ranks the rest, and a maximum keeps the top N. | Eligibility criteria, screens, and selection |
| Position sizing | The weight expression sets each selected security's weight. Without one, Tilt sizes by score. | Weighting scheme |
| Ticker overrides | Forces specific securities in or out. | Discretionary inclusions and exclusions |
| Rebalance and concentration | Sets the rebalance schedule and caps position weights. | Rebalance schedule and capping |

The result is the Tilt's constituents: the selected securities and their weights on the evaluation date.

## Find your way around

Select a Tilt in Library to open its Tilt view. In chat, select **View details** on a Tilt card or select a Tilt reference in a sent message to open the same view without losing your place in the chat.

Use [**Chats** to find or switch conversations](/tilt-agent/overview#find-and-switch-chats). Keep the Tilt open and check [**Looking at**](/tilt-agent/ask-about-page) above the message input before asking about its rules or results. On your phone, chat opens over the Tilt; close chat to return to it.

![The Tilt view with numbered callouts: 1 close, 2 the Methodology and Portfolio tabs, 3 the backtest, 4 the methodology sections, 5 the actions menu, 6 the History panel](https://mintcdn.com/tilt/Fc-t_XUO5MaEY31N/images/index-construction/navigate-tilt-view.png?fit=max\&auto=format\&n=Fc-t_XUO5MaEY31N\&q=85\&s=46e96a7cc8f727bb552adc451e57045a)

The Tilt view, with History open.

1. **Close** returns to the chat. A Tilt opened from Library shows **Back to Library** instead.
2. **Methodology** shows the rules and a backtest. **Portfolio** lists the constituents and weights.
3. The backtest compares the Tilt with a benchmark over a period you choose, with risk statistics.
4. The methodology sections hold the construction rules, one section per stage. Open a section and edit it. Each edit joins the change queue at the bottom of the Tilt view. Open the queue and select **Apply** to save the changes and re-evaluate the Tilt.
5. The actions menu has **History**, **Export to Excel**, and **Publish to Marketplace**.
6. **History** lists every methodology change, with who made it and when.

After opening a Tilt from Library, select **Explore in chat** and choose a suggested question or **Ask anything**. New Chat opens with an editable draft and the Tilt attached. Nothing is sent until you select **Send**.

When you ask Tilt Agent for a change in the chat, it edits the same rules you see in the Tilt view.

## Read the backtest

The backtest on a Tilt's **Overview** tab runs the Tilt's current rules over a period and compares the result with a benchmark. The benchmark button under the chart names the benchmark the backtest used. To compare with another fund, click it and pick SPY, QQQ or DIA, or search for any supported ETF by ticker or name, such as ACWI or EFA. Choosing a benchmark or a period runs the backtest again.

A Tilt whose rules use a [custom AI-scored column](/index-construction/expressions) (`enrichment()`) can't be run on past dates, so its chart is a backcast: it holds the Tilt's latest saved basket, at its current weights, for the whole period. Read a backcast as a hindsight view of today's basket. The rules didn't pick those holdings on past dates.

The summary beside the chart shows the Tilt's **Return**, the benchmark's return, and the **Relative** return between them, with these risk statistics:

| Statistic | What it measures |
| - | - |
| **Max drawdown** | The largest fall from a peak during the period. |
| **Sharpe ratio** | Return relative to volatility. |
| **Volatility** | How much the Tilt's returns varied. |
| **Beta** | How much the Tilt moved with the benchmark. |
| **Average annual turnover** | Simulated rebalance turnover per year, not counting the first purchase. |
| **Historical TE vs** *benchmark* | Historical tracking error: how much the Tilt's daily returns differed from the benchmark's, annualized. A higher number means the Tilt behaved less like the benchmark. |

Historical tracking error describes this backtest only. It isn't the tracking error of a live account or a sleeve, and it isn't a target. It reads **Unavailable** when the period doesn't have enough days with returns for both the Tilt and the benchmark.

If the backtest leaves out tickers it can't support, a note under the chart lists them, and the figures describe only the tickers it kept.

## A first example

This Tilt takes US companies worth more than \$5 billion with strong free-cash-flow margins, ranks them by revenue growth and return on equity, and holds the top 20 by free-float market cap:

| Rule | Value |
| - | - |
| Universe | US Investable Equities |
| Filter expression | `market_cap > 5000 and fcf_margin > 0.08` |
| Score expression | `2 * revenue_growth_3y + roe` |
| Maximum constituents | `20` |
| Weight expression | `free_float_market_cap` |
| Rebalance | Quarterly |

`market_cap` is in millions of US dollars.

## Next steps

> [card] [Expression reference](/index-construction/expressions)
>
> Fields, operators, and functions for each rule.

> [card] [Selection and weighting](/index-construction/selection-and-weighting)
>
> How filters, scores, limits, weights, and caps combine.

> [card] [Build a thematic Tilt](/index-construction/example-nuclear-energy)
>
> Build and refine a nuclear energy Tilt with Tilt Agent.

> [card] [Choose an integration](/index-construction/choose-an-integration)
>
> Compare Tilt's interface, Tilt Agent over MCP, and the REST API design preview.


# Selection and weighting
Source: https://docs.tilt.now/index-construction/selection-and-weighting

How the universe, filter, score, top-N limit, weights, overrides, and caps combine into a Tilt's constituents.

Tilt evaluates the construction rules in this order. Each step works on the output of the step before it.

1. Start from the eligible universe.
2. Compute derived fields.
3. Keep securities where the filter expression is true.
4. Rank the remaining securities by score, highest first. If you set a maximum, keep the top N.
5. Weight each selected security by the weight expression, or by score when the weight expression is blank. Scale the weights to sum to 100%.
6. Apply concentration caps by issuer and redistribute the removed weight so the portfolio remains at 100%.

Ticker overrides adjust the result. Always-included tickers stay in the Tilt, and Tilt removes always-excluded tickers after the rules run.

## Universe

![Universe section with eligible universe US Investable Equities and reference date 2026-08-01](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-universe.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=70133294d2e580adf0bb37ade3650a6e)

The eligible universe is the set of securities the rules evaluate, such as US Investable Equities. To build from a named index's members, keep a broad universe and add `index("<name>") > 0` to the filter.

The reference date anchors size-segment eligibility to a point in time. Tilt then takes size segments from recorded history with buffer bands, so a company near a size boundary stays put through small price moves.

## Filter, score, and maximum constituents

The filter expression sets eligibility. A security that fails it drops out.

The score expression ranks eligible securities, highest first.

Maximum constituents keeps the top N ranked securities and requires a score expression. With no score expression, the Tilt holds every security that passes the filter.

## Position sizing

![Position sizing section with weight expression size\_basis](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-position-sizing.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=7f14e700e13b53cb07998b8dff004dd1)

The weight expression sets position sizes for the selected securities, separate from the score that ranked them. You can pick the top 20 by quality and hold them by market cap. Leave it blank to size by score.

| Goal | Score expression | Weight expression |
| - | - | - |
| Equal weight, no ranking | blank | blank |
| Market-cap weight | Your ranking, or blank | `market_cap` |
| Free-float market-cap weight | Your ranking, or blank | `free_float_market_cap` |
| Weight by the ranking | Your ranking | blank |
| Weight by theme exposure | `theme("<label>")` | blank |

A constant weight such as `1` gives each listing of a multi-listing company its own full position. `theme()` selects companies, so size a thematic Tilt by score and leave the weight expression blank. Tilt rejects a weight expression on a company-level selection when a selected company has more than one listing.

## Ticker overrides

![Ticker overrides section with NVDA always included and TSLA always excluded](https://mintcdn.com/tilt/o-tckvx-QtAfvO7i/images/index-construction/rail-ticker-overrides.png?fit=max\&auto=format\&n=o-tckvx-QtAfvO7i\&q=85\&s=e4af538593c810943277250cef7f256b)

**Always include** keeps a ticker in the Tilt whether or not it passes the rules. **Always exclude** removes a ticker after the rules run.

Use overrides for named securities. Put group rules, such as a sector exclusion, in the filter expression.

A symbol can match more than one security, such as one ticker on two exchanges, so each override names one listing. On the Methodology tab, search for the ticker and pick the listing by name and exchange. Tilt Agent asks which listing you mean before it saves.

## Rebalance and concentration

![Rebalance and concentration section with quarterly cadence, next rebalance Dec 18, 2026, and threshold-based concentration limits](https://mintcdn.com/tilt/CizYNoSLp0Sv3sdD/images/index-construction/rail-rebalance-concentration.png?fit=max\&auto=format\&n=CizYNoSLp0Sv3sdD\&q=85\&s=cb9e80ce6a8688c714858969789339ce)

Index cadence sets how often Tilt re-evaluates constituents and weights: monthly, quarterly, semi-annually, or annually. Rebalances fall on the third Friday of the scheduled month, or the previous trading day when that Friday is a market holiday. A published index skips any rebalance in its first 45 days.

When the filter uses `index("<name>") > 0` and you set no cadence, Tilt adopts that index's published reconstitution schedule.

Concentration method caps issuer weights after selection and sizing. When an issuer has multiple listings, Tilt combines their weights before applying the limits:

| Method | Effect | Settings |
| - | - | - |
| None | Keeps the weights that sizing produced. | None |
| Top N | Limits the combined weight of the largest issuers. | Top positions, combined maximum |
| Threshold | Limits issuers above a set portfolio weight. | Weight threshold, combined maximum |

Top N and Threshold also accept a single-position maximum. Leave any limit blank to turn it off.

When a cap reduces an issuer's weight, Tilt redistributes the removed weight proportionally among issuers that can receive it without exceeding the limits. The final weights sum to 100%. Tilt then divides a multi-listing issuer's final weight based on each listing's free-float market capitalization. If Tilt cannot calculate that split from float data, it preserves the listings' relative weights from before capping.


# Working copies and published versions
Source: https://docs.tilt.now/index-construction/working-copies-and-published-versions

Understand the version you are editing, public releases, Marketplace listing, and sleeve use.

A Tilt can have an editable working copy and published versions at the same time. Publishing creates a public release. You can keep editing the working copy while others view a published version.

![One Tilt has an editable working copy and public published versions. Marketplace listing controls whether those published versions appear on the author's profile.](https://mintcdn.com/tilt/oDy4SD9TsUtfkVjr/images/index-construction/publication-model.svg?fit=max\&auto=format\&n=oDy4SD9TsUtfkVjr\&q=85\&s=ed228e768d227f5d85eb4bc3d6e03dcd)

## Check the version you are viewing

The Tilt view's header identifies the selected version. **Viewing working copy** means you are viewing the editable version. **Viewing published v1** identifies a public release; older releases may show **Viewing published version** without a number.

![Tilt view header showing Explore in chat, Viewing working copy, and the actions menu.](https://mintcdn.com/tilt/oDy4SD9TsUtfkVjr/images/index-construction/viewing-working-copy.png?fit=max\&auto=format\&n=oDy4SD9TsUtfkVjr\&q=85\&s=934934c19a39687964bc551a40373677)

The Tilt view identifies the working copy beside the actions menu.

When the latest published version differs from the version you are viewing, **Latest published** opens it in a new tab. A working copy can match a published version or contain edits. Its label alone does not tell you whether the contents differ.

## Read the Library labels

Library describes the whole Tilt, including its public versions.

| Label | Meaning |
| - | - |
| Only you | A personal Tilt with no published version. |
| Your team | A Tilt in your team's workspace with no published version. Access restrictions still apply. |
| Listed in Marketplace | The Tilt appears on its author's Marketplace profile. |
| Not listed · Public version available | The Tilt has a public version, but no Marketplace listing. |

## Publish or remove a listing

**Publish to Marketplace** makes the latest version public, lists it on your profile, and notifies followers. Tilt asks you to confirm before publishing.

**Remove Marketplace listing** removes the Tilt from your profile. Published versions keep their public links, and followers receive no notification. Removing a listing does not make those versions private.

**Submit as an Index** starts a separate index-submission review. Marketplace publication alone does not make a Tilt an index.

## Use a working copy in a sleeve

For a sleeve, choose a working copy your advisor workspace can access. You do not need to publish it first. Subscription and other access requirements still apply. Check which sleeves use the working copy before saving edits, and [review a rebalance](/advisor/review-rebalance) before submitting trades.

[Build a model portfolio](/advisor/build-model-portfolio) explains sleeve allocation and implementation choices.


# Marketplace API
Source: https://docs.tilt.now/introduction

Index levels, constituents, and corporate actions for the indexes your organization subscribes to, plus index governance notifications.

The Marketplace API returns data for the indexes your organization subscribes to: levels and their history, constituents, and corporate actions. It also returns your organization's Tilts and their details.

The notifications endpoint lists governance notifications for all published indexes. Add `subscribed=true` to return only notifications for the indexes your organization subscribes to.

## Get started

1. Confirm that your organization has an active Tilt subscription.
2. Follow the [Marketplace API quick start](/quick-start) to authenticate and make your first request.

> [card] [Quick start](/quick-start)
>
> Authenticate and make your first request.

> [card] [List indexes](/api-reference/endpoint/list-indexes)
>
> Start with the indexes your organization can access.


# Marketplace API quick start
Source: https://docs.tilt.now/quick-start

Authenticate and make your first Marketplace API request.

## Overview

### Base URL

```bash theme={null}
https://api.tilt.now
```

### Authentication

All API endpoints require authentication using an API token. Include your API token in the header of each request:

```bash theme={null}
x-api-key: <your_api_token>
```

### Getting Your API Token

1. Log in to your [Tilt dashboard](https://tilt.io)
2. Click the gear icon in the bottom left of the dashboard
3. Select `API Keys` from the menu
4. Enter API key name and create a new key

> [!NOTE]
>
> Keep your API token secure and never share it publicly. If your token is compromised,
> you can revoke it and generate a new one from your dashboard.

## Making Your First API Calls

### 1. List Indexes

Get a list of all indexes you have access to:

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/indexes" \
  -H "x-api-key: YOUR_API_TOKEN"
```

[View full API reference →](/api-reference/endpoint/list-indexes)

### 2. Get Index Details

Fetch detailed information about a specific index:

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/indexes/{index_uuid}" \
  -H "x-api-key: YOUR_API_TOKEN"
```

Replace `{index_uuid}` with an actual index ID from step 1.

[View full API reference →](/api-reference/endpoint/get-index-details)

### 3. Get Index Levels

Retrieve the levels for your index:

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/indexes/{index_id}/levels" \
  -H "x-api-key: YOUR_API_TOKEN"
```

Replace `{index_id}` with the same index ID you used in step 2.

[View full API reference →](/api-reference/endpoint/get-index-levels)

### 4. Get Index Constituents

Retrieve constituents for your index:

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/indexes/{index_id}/constituents" \
  -H "x-api-key: YOUR_API_TOKEN"
```

[View full API reference →](/api-reference/endpoint/get-index-constituents)

### 5. Get Index Corporate Actions

Retrieve corporate actions for your index:

```bash theme={null}
curl -X GET "https://api.tilt.now/api/v1/indexes/{index_id}/corporate-actions" \
  -H "x-api-key: YOUR_API_TOKEN"
```

[View full API reference →](/api-reference/endpoint/get-index-corporate-actions)

### Important Reminders

> [!NOTE]
>
> Remember to replace `YOUR_API_TOKEN` with your actual API token in all requests.


# Ask about the page
Source: https://docs.tilt.now/tilt-agent/ask-about-page

Ask Tilt Agent about the page or item you are viewing.

Open a page such as **Trading** or **Clients**, or an item such as a Tilt or saved backtest, then open chat. On desktop, chat appears beside the page; on your phone, it opens over the page. **Looking at** above the message input names the page or item Tilt Agent includes with your next question. You can ask about it without repeating its name.

![Chat composer showing Looking at Tax gamma: 0 vs 100 above the Ask Tilt input](https://mintcdn.com/tilt/JL3_bqriPaIbagvu/images/tilt-agent/looking-at-backtest.png?fit=max\&auto=format\&n=JL3_bqriPaIbagvu\&q=85\&s=5db15b9366a2390861990e40e71f4270)

Looking at names the saved backtest included with your question.

## Ask about a sidebar page

On a page you open from the sidebar, such as **Trading** or **Clients**, **Looking at** names the page, and Tilt Agent reads what the page shows. It reads the tab you have open. On **Clients**, **Sleeves**, and **Library**, it also reads your search and filters, so "these" in your question means the rows on screen. Tilt Agent does not see the search or filters on **Trading**, so name the household or account you mean there.

![Chat composer showing Looking at Trading above the Ask Tilt input, with the Trading page's To review tab beside it](https://mintcdn.com/tilt/scxvm2HUF_7uEaMq/images/tilt-agent/looking-at-trading.png?fit=max\&auto=format\&n=scxvm2HUF_7uEaMq\&q=85\&s=06ef41f86e76d7ed57c7a7416a610b59)

Looking at names the Trading page beside the chat.

| Page | Tilt Agent reads | Try asking |
| - | - | - |
| **Trading** | The accounts waiting in **To review**, or the orders and their status in **Sent** | "Which accounts are waiting on my review?" |
| **Alerts** | Your alerts | "Summarize these alerts." |
| **Clients** | The households or clients that match your search | "Which of these households have the most assets?" |
| **Firm** | The firm's total, its **Holdings**, **History**, or **Setup**, whichever tab is open | "Which defaults do new accounts inherit?" |
| **Models** | Your models | "Which of these models has the most assets?" |
| **Sleeves** | The sleeves that match your filters | "Which of these sleeves are composites?" |
| **Automations** | Your automations | "Which automations do I have set up?" |
| **Library** | Your Tilts, posts, and dashboards, by the type you choose | "Which Tilts did I save this month?" |

In **Library**, Tilt Agent cannot read the **Files** or **Reports** lists. Home and **Settings** show no **Looking at**.

To ask about one row, open it. **Looking at** then names that client, account, or other item.

## Ask a follow-up about a backtest

With a **Tax gamma: 0 vs 100** backtest open, ask:

> Why did gamma 100 do better here?

Tilt Agent reads that saved comparison's inputs and results. If the account's Setup has changed since the run, the backtest still records the experiment you ran. Ask about the current Setup when you want to assess today's settings.

## Change the subject

Open a different page or item and check **Looking at** before sending. Tilt Agent includes the page or item you are now viewing with the next message. Your earlier messages remain in the chat.

Switching chats keeps **Looking at** tied to the page you are viewing. It does not change the page to match an earlier conversation.

Name any other items you want to compare in your question. If you do not see **Looking at**, name what you mean.

## Ask about several tabs in Tilt for Mac

In [Tilt for Mac](/tilt-agent/page-tabs), each page you open keeps a tab. **Looking at** names the page in the tab on screen, and **+N open tabs** beside it lists the other tabs Tilt Agent also receives, sidebar pages included. Ask about them together without naming each one, such as "Compare this Tilt with the one in my other tab."

## Ask from your phone

1. Open the page you want to discuss, then tap **Chat**. The chat sheet opens with a small part of the page visible above it.
2. Check **Looking at** above the message input, then ask your question. The page stays in context for follow-up messages.
3. Tap **Close chat** to return to the page. You can also drag down from the chat header. Scrolling or pulling down in the conversation leaves chat open.

Reopen chat to continue the conversation. On a fresh page visit, chat starts closed. To change the page included with your questions, close chat, open another page, and check **Looking at** when you reopen it.

See [Find and switch chats](/tilt-agent/overview#find-and-switch-chats) to choose another conversation without leaving the page.


# Background jobs
Source: https://docs.tilt.now/tilt-agent/background-jobs

Hand longer work to Tilt Agent and keep talking in the same chat.

A background job is work Tilt Agent does on its own while you keep using the chat. When the job ends, its result comes back to the chat that started it.

Each [automation](/tilt-agent/create-automation) occurrence also runs as a separate background job. It starts fresh from the automation's saved instructions and reports back to **Main**, while you continue your conversation in Main.

## Start a job

Ask for the work to run in the background, and name each job so you can tell them apart:

> In the background, start three jobs for AAPL, JPM, XOM, JNJ and NEE: earnings check finds each one's latest quarterly results, news check finds the most recent headline for each, and analyst check finds the current consensus rating. Each reports back with a short table.

When you ask for background work, Tilt Agent starts a job. It can also start one on its own for a long task. Jobs run side by side, and you can keep asking questions while they work. A job keeps working after you close Tilt, and after your firm signs you out for [inactivity](/advisor/inactivity-logout).

## Follow a job

| Where | What you see |
| - | - |
| The chat | A row with the job's name, what it is doing, and how long it has worked. |
| The title bar | The job's name. With several jobs, the count, such as **2 running**, which opens a list of them. |

Select the row, the name in the title bar, or a job in the list to open the job's page. The page shows the instructions Tilt Agent gave the job and the job's work as it happens. It has no message box: you talk to a job through the chat that started it.

For an automation job, the header links to the automation and shows the occurrence's date and time. The title-bar list contains current work only. Open **Automations** for the full automation run history, including older runs and runs that found nothing to report.

## Add work or stop a job

| To | Do this |
| - | - |
| Give a running job more to do | Ask in the chat: "Tell news check to add MSFT." |
| Stop one job | Select **Stop** at the top of the job's page, or ask in the chat. For an automation, this ends that occurrence and leaves its schedule in place. |
| Stop the listed jobs | Open the list from the title bar, select **Stop all**, then select **Stop all jobs?** to confirm. This targets the jobs shown when you began confirmation, excluding jobs that start afterward. |
| Stop Tilt Agent's reply | Select Stop in the message box. Your background jobs keep running. |

## Read the result

When a job ends, the chat shows a note: **news check finished**, followed by the start of its answer, or **news check failed** with the reason. Select the note to open the job's page and read the full answer. Tilt Agent can follow the note with a reply of its own, such as a summary table.

Automations with a meaningful-update-only policy stay quiet when nothing changes. Inspect those runs in **Automations**. To prevent future occurrences, **Pause** the automation; occurrences already accepted to run can finish.

## Choose a job, another chat, or an automation

| Use | When you want |
| - | - |
| A background job | One piece of work done now, with the result back in this chat. |
| Another chat | Tilt Agent to hand work to a chat that keeps its own history. See [Work across chats](/tilt-agent/overview#work-across-chats). |
| An automation | The same assignment repeated on a schedule. See [Create an automation](/tilt-agent/create-automation). |


# Change reviews
Source: https://docs.tilt.now/tilt-agent/change-reviews

Compare proposed changes with saved settings before applying them.

A change review shows what Tilt Agent proposes to save, alongside the current values. Use it to check a Tilt's rules or an account's settings before deciding whether to apply the changes.

![Update Energy Research review showing Methodology / cadence changing from QUARTERLY to MONTHLY, with Discard and Apply buttons](https://mintcdn.com/tilt/CVJ4FMmJkpznQNOQ/images/tilt-agent/change-review.png?fit=max\&auto=format\&n=CVJ4FMmJkpznQNOQ\&q=85\&s=0a2a8ff8c2de1e1cd780220013e37952)

A review of Energy Research's proposed switch from quarterly to monthly cadence.

## Decide what to save

Preparing a review leaves saved settings unchanged. Check the object being changed and the values shown in the review.

| Your decision | What happens |
| - | - |
| **Apply** | Tilt saves the proposed changes and reports the result. |
| Ask for a revision in chat | Tilt Agent prepares an updated review. Use the latest review to make your decision. |
| **Discard** | Tilt closes the pending review without applying its remaining changes. |

For example, you can reply, "Use annual instead of monthly," before applying. The earlier review becomes inactive when the replacement is ready.

## Ask to review first

> Show me a change review to switch Energy Research from quarterly to monthly rebalancing. Leave everything else unchanged, and do not apply it yet.

In this example, rebalancing and membership selection share a cadence, so the review changes both. Read Tilt Agent's explanation alongside the proposed values.

Tilt Agent can also make changes directly when your request and permissions allow it. Ask to review first when you want to see proposed values before saving.

## Review firm trade release rules

Ask explicitly for a Change Review when changing [trade release rules](/advisor/trade-release-rules):

> Prepare a Change Review for our firm's trade release rules. Add a Large trades rule for security trades greater than \$100,000, with Tyler as the eligible sender. Preserve the other rules and show the complete policy before and after. Do not apply it yet.

Check the firm, each rule's enabled setting, conditions, and eligible members. The review covers the complete policy, including rules you intend to keep. **Apply** replaces that policy and requires an organization owner. If the saved policy has changed since the review, ask for a fresh review before applying.

Saving release rules does not grant trading permission or send a proposal. Reviewers make a separate [trade decision in Trading](/advisor/review-rebalance#review-the-morning-trading-queue).

## Review sleeve changes

Tilt Agent also proposes changes to model sleeves as change reviews:

| Request | What the review changes |
| - | - |
| Tilts or direct indexing on one of an account's sleeves, at any level of its model | That account only. A change inside a composite applies at that place; direct indexing on a top-level sleeve also applies wherever that sleeve appears inside a composite, unless the account sets that place separately. |
| What a composite holds: its sleeves, their targets, and the tilts and direct indexing it gives each | The composite, for every model that holds it |

A composite is shared, so Tilt Agent names the models that hold it before it proposes the change. The review lists those models and counts the accounts that set a changed sleeve differently from the model. It shows what the composite holds before and after: a sleeve the proposal leaves out is removed, and a sleeve it names for the first time is added. The targets must total exactly 100%.

![Update US Large Cap setup review naming 4 models, Global 80/20, Global 60/40, Growth Core, and Income & Real Assets, and 1 account that sets US Large Value (IUSV) differently from the model and keeps its own settings. Sleeve, Holds: before, US Large Growth (IUSG) 55% and US Large Value (IUSV) 45%; after, US Large Growth (IUSG) 60% and US Large Value (IUSV) 40%, direct indexed; with Discard and Apply buttons.](https://mintcdn.com/tilt/9xzL1smQgfroOreu/images/tilt-agent/composite-change-review.jpg?fit=max\&auto=format\&n=9xzL1smQgfroOreu\&q=85\&s=4c9eef787c184b98cbbeac5eb67eaa66)

A review of a change to the shared US Large Cap composite: 55/45 to 60/40, with US Large Value direct indexed.

> Change the shared US Large Cap sleeve to 60% US Large Growth and 40% US Large Value, and direct index US Large Value inside it. Show me a change review first.

After you apply, Tilt Agent can read the model's tree back to confirm the saved targets. [Models and benchmarks](/advisor/models-and-benchmarks#composites-are-shared) explains how far a composite change reaches.

## Check the result

Read the result after applying. If only some changes succeeded, those changes remain saved. Discarding the remainder does not undo them.

If the result is unclear, ask Tilt Agent to check what was saved before trying again. To reverse an applied change, request a new change.

> [!NOTE]
>
> Applying a settings review does not submit trades. Trading has its own [rebalance review and submission flow](/advisor/review-rebalance).


# Connect an MCP server to Tilt Agent
Source: https://docs.tilt.now/tilt-agent/connect-mcp-server

Connect an external service to Tilt Agent, authorize access, choose what Tilt Agent may do with each of its tools, and manage the connection in Settings or chat.

Connect an external service through the Model Context Protocol (MCP) so Tilt Agent can use that service's tools in your chats. This guide connects Linear with its read-only MCP endpoint.

## Before you start

You need access to **MCP connections** in Tilt and an account with the provider you want to connect. Open **Settings > Connections** to check whether the MCP section is available to you.

Use the provider's public HTTPS MCP server URL. Tilt supports servers that need no sign-in and servers that advertise compatible OAuth authorization with PKCE. Localhost servers, private network addresses, and URLs containing credentials, query parameters, or fragments are unsupported. Sign in through the provider's authorization page; keep passwords and API keys out of chat and the URL field.

For this walkthrough, use:

```text theme={null}
https://mcp.linear.app/mcp/readonly
```

[Linear's read-only endpoint](https://linear.app/docs/mcp) exposes tools for reading Linear data. Review the provider's consent page to confirm the account, workspace, and permissions you are authorizing.

## Connect from Settings

1. Open your user menu and select **Settings**.
2. Select **Connections**, then find **MCP connections**.
3. Select **Add**, paste the Linear endpoint into **MCP server URL**, and select **Add server**. Tilt discovers the server's authorization requirements.
4. On Linear's authorization page, sign in and review the requested access. Authorize Tilt for the workspace you want to use.
5. After authorization, return to Tilt. The server's row shows a check under **Status** once it's connected.

To find a server in a long list, type part of its name or web address in **Search**, or use the filter button beside it to show only **Connected** or **Not connected** servers.

![MCP connections in Tilt with the Add form open, the Linear read-only endpoint entered in MCP server URL, and an Add server button](https://mintcdn.com/tilt/qgv9sSZRL-lkCCET/images/tilt-agent/mcp-server-url.png?fit=max\&auto=format\&n=qgv9sSZRL-lkCCET\&q=85\&s=4a4f61848f0ce0d31e153c7bcc5a3a7a)

Select Add, then enter the provider's MCP endpoint.

![MCP connections list in Tilt with Search, a filter button and Add above a table of Connector, Server and Status: two servers with a check, and one with a warning sign and a Connect button](https://mintcdn.com/tilt/qgv9sSZRL-lkCCET/images/tilt-agent/mcp-server-connected.png?fit=max\&auto=format\&n=qgv9sSZRL-lkCCET\&q=85\&s=39c0bf5bc3303341357129a14f2ba4ee)

Servers in Settings > Connections: a check means connected, and a warning sign means the server needs you to connect it.

Tilt keeps provider credentials server-side. A connection is yours in the organization you made it in, and nobody else in that organization can use it. Each organization you work in has its own connections, sign-ins and tool permissions, so to use the same server in another organization, connect it again there.

## Connect from chat

You can also ask Tilt Agent to prepare a connection:

```text theme={null}
Connect this MCP server: https://mcp.linear.app/mcp/readonly
```

Tilt Agent discovers the server and presents a confirmation card. Review the server URL, active organization, provider scopes, and Tilt callback hostname. Select **Connect** to begin provider authorization, or **Cancel** to leave the connection unchanged. Discovery alone does not authorize access.

Complete the provider's authorization flow. Tilt then confirms the connection in chat; its tools are available on your next turn. If a confirmation has expired or its context has changed, ask Tilt Agent to prepare a new one.

For a server that needs no sign-in, the card says so, and **Connect** connects it right away. If the provider must approve Tilt first, Tilt Agent tells you and prepares no card; see **Provider approval required** under [Resolve a connection problem](#resolve-a-connection-problem).

## Use the connection

After connecting, ask Tilt Agent for an outcome that uses the provider. For example:

```text theme={null}
Find my open Linear issues and summarize which ones need attention this week.
```

The provider's tools, your authorized access, and your tool permissions determine what Tilt Agent can do. With the Linear read-only endpoint, requests can read data; they cannot create or update Linear issues.

## Choose what Tilt Agent may do with each tool

Each app labels its own tools: some as tools that only read data, others as tools that can change or delete data. Tilt can't check those labels. Out of the box, Tilt Agent runs a tool the app labels read-only on its own, and every other tool needs your approval, including a tool the app doesn't label at all.

To change that for one app:

1. Open **Settings > Connections** and find the server under **MCP connections**.
2. Select the server's name. Its page shows the app's name and its server's web address, with a button to copy it, then lists the tools the app offers Tilt Agent under **Tool permissions**.
3. Set a tool with the three icons beside it: **Always allow** (a check in a circle), **Needs approval** (a raised hand), or **Blocked** (a circle with a line through it). Point at an icon, or move to it with the keyboard, to see its name.
4. To set every tool in a group at once, open the menu beside the group's name and choose a setting. The menu shows **Custom** when the group's tools don't all have the same setting. Select a group's name to collapse or expand it.

You can also open the page from a chat. A connected app's card has a **Tool permissions** button next to **Details**. Under each of Tilt Agent's answers, a line names each connected app tool it called without asking you, such as "Used Get market chart on Market Charts"; a call you approve shows on its approval card instead. The gear at the end of that line, the gear at the end of each "You ran" line on a connected app's card, and the **Tool permissions** link on an approval card open the page at their tool and highlight it for a moment.

![The page for mcp.deepwiki.com: its server URL with a copy button, Tool permissions with the line Choose when Tilt Agent is allowed to use these tools, then Write/delete tools with a count of 3 and a Needs approval menu, and three tools, each with three icon choices and Needs approval selected](https://mintcdn.com/tilt/qgv9sSZRL-lkCCET/images/tilt-agent/mcp-tool-permissions.png?fit=max\&auto=format\&n=qgv9sSZRL-lkCCET\&q=85\&s=cca112754dd86d0e4f31fc6540d8f7e5)

A test server whose tools carry no labels, so every tool is under Write/delete tools and needs approval.

| Choice | What Tilt Agent does |
| - | - |
| **Always allow** | Calls the tool without asking you. |
| **Needs approval** | Asks you first. In a chat, Tilt Agent shows a card with the tool and the exact values it wants to send, and nothing is sent until you allow it. |
| **Blocked** | Doesn't see the tool at all. The app's own views can't call it either. |

The app's own views in a chat follow the same choices for these tools. When a view calls a tool that needs your approval, Tilt asks you before the call runs. A tool the app keeps for its view alone isn't listed here, and Tilt runs it right away when the view asks. See [When a view runs a tool](/tilt-agent/connected-app-views#when-a-view-runs-a-tool).

The page groups tools, with the number of tools beside each group's name and the tools in each group sorted A to Z. **Interactive tools** holds the tools that come with the app's own view (see [See an app's own view](#see-an-apps-own-view)). **Read-only tools** holds the other tools the app labels as ones that only read data. **Write/delete tools** holds every other tool, including tools the app doesn't label.

Tilt Agent uses your choices from its next turn. A turn that's already running can take several minutes to pick them up. A tool the app adds later starts with the default for its label until you choose otherwise. If Tilt can't reach the app to list its tools, the page says so; select **Retry** to try again. To list the app's tools again at any time, open the more actions menu beside **Disconnect** and select **Refresh tools list**.

Automations can't ask you during a run, so a tool that needs approval doesn't run in an automation. Set a tool to **Always allow** if an automation has to use it. A background job can't ask you either: it stops and asks Main chat to check the call with you. Chats started from another app, such as Claude, don't use the tool either.

## Approve or deny a call in the chat

When Tilt Agent wants to use a tool that needs approval, it stops and shows a card in the chat. The card names the app, its real web address, and the tool, and lists every value Tilt Agent wants to send, exactly as it would send them. The app's name and the tool's title come from the app.

* **Allow once** sends that exact call to the app, once. Tilt Agent then carries on from the app's answer. If the tool comes with its own view, such as a chart, Tilt shows the view below the card.
* **Always allow** sets the tool to **Always allow** on its Tool permissions page, then sends the call once, like **Allow once**. From then on Tilt Agent uses the tool without asking. If Tilt can't save the setting, the call is still allowed once and the card says so. The card offers it only for a tool you haven't set yourself: a tool you set to **Needs approval** keeps asking.
* **Deny** sends nothing, and Tilt Agent is told you declined.

A card nobody answers expires after 24 hours and counts as denied. If the app changes the tool, stops offering it, or you set it to **Blocked** before the call goes out, Tilt doesn't send it and the card says so.

## See an app's own view

Some apps send their own view with a result, such as a chart with buttons. Tilt shows it in the chat inside a card labelled **Connected app**. Everything inside the card's frame is the app's own page. Tilt draws the frame around it: the app's name and web address, and a line for each action the view runs that can change something in the app. When the view uses one of the tools the app also offers Tilt Agent, Tilt follows your choices on the app's **Tool permissions** page and asks you first when a tool needs your approval.

For what each part of the card means, what a view can and can't do, and what Tilt Agent sees, read [Connected app views](/tilt-agent/connected-app-views).

## Reconnect or disconnect

Open **Settings > Connections**, find the server under **MCP connections**, and select its name to open its page.

| Action | What to do |
| - | - |
| Reauthorize a connected server | Open the more actions menu beside **Disconnect**, select **Reconnect**, and complete provider authorization again. |
| Finish authorization | Select **Connect** on the server's page, or on its row in **Settings > Connections**. |
| Stop using a server | Select **Disconnect**. Tilt removes access for future turns, and the app's views in your chats stop loading. |

You can also ask Tilt Agent to reconnect or disconnect a server in chat. Review the confirmation card and select the matching action. A request to disconnect prepares a confirmation; Tilt applies it when you select **Disconnect**.

## Resolve a connection problem

A server that isn't connected shows a warning sign and a **Connect** or **Retry discovery** button on its row in **Settings > Connections**. Point at the button to see why, or open the server's page, which names its status.

| Status or message | Next step |
| - | - |
| **Authorization required** | Select **Connect** and finish signing in with the provider. |
| **Provider approval required** | Ask the provider's administrator to approve Tilt's callback hostname shown on the server's page, or arrange an approved OAuth client configuration. Then try **Connect** again. |
| **Unsupported** | Confirm that the provider supports OAuth with PKCE. After the provider corrects compatibility, select **Retry discovery**. |
| **Unavailable** | Check the MCP endpoint and the provider's availability. Tilt could not read compatible server metadata. Select **Retry discovery** after correcting the problem. |
| Authorization was not completed | Check the provider's approval and access settings, then connect again. |
| Your session expired | Refresh Tilt and sign in again before retrying. |

For an integration that sends tasks to Tilt Agent from another application, see [Delegate to Tilt Agent from your application](/tilt-agent/connect-over-mcp).


# Delegate to Tilt Agent from your application
Source: https://docs.tilt.now/tilt-agent/connect-over-mcp

Connect an application to Tilt Agent, authorize a user, delegate work, consume run results, and continue a session.

Connect to Tilt Agent over the Model Context Protocol (MCP) when your
application owns the chat or agent experience. Your application acts as the MCP
host and client; Tilt Agent acts as a specialist sub-agent for supported
investment workflows.

Send a complete outcome to Tilt Agent instead of decomposing it into generic
searches or individual construction operations. For example, delegate “Create
a quarterly nuclear energy Tilt with 25 constituents and a 10% position cap,”
then continue the same Tilt Agent session when the user asks for a change.

## Understand the connection

The integration has four separate layers:

| Layer | Purpose |
| - | - |
| MCP over HTTP | Discover tools and resources, then invoke them with JSON-RPC. |
| OAuth | Authorize the connection as a Tilt user. |
| Tilt Agent tools | Start work, read progress and results, continue, cancel, or close a session. |
| MCP Apps | Optionally render Tilt's interactive session UI inside a supporting host. |

The remote MCP endpoint is:

```text theme={null}
https://tilt.now/mcp/tilt
```

Tilt supports two protocol paths:

* MCP `2026-07-28` uses `server/discover` and request-scoped transport state.
* MCP `2025-11-25` compatibility uses `initialize` and stateless transport.

Use an MCP SDK to negotiate the protocol. Do not use an MCP transport session
as Tilt Agent conversation state: conversation continuity comes from the
`session_id` returned by `delegate_to_agent`.

The server exposes tools and resources. It does not expose an MCP prompt
catalog.

## Authorize the user

Tilt uses OAuth 2.0 authorization code flow with S256 PKCE. A capable MCP client
can discover the authorization flow from the endpoint:

1. An unauthenticated MCP request returns `401 Unauthorized`. The
   protected-resource metadata appears in the response's
   `WWW-Authenticate` challenge.
2. [RFC 9728 protected-resource metadata](https://www.rfc-editor.org/rfc/rfc9728)
   identifies the authorization server, required `mcp` scope, and exact
   resource `https://tilt.now/mcp/tilt`.
3. Authorization-server metadata advertises the authorization, token, and
   dynamic client registration endpoints.
4. The client registers its callback, creates a PKCE verifier and S256
   challenge, and sends the user to Tilt to sign in and consent.
5. The client exchanges the authorization code for a resource-bound access
   token and sends it as `Authorization: Bearer <access_token>` on MCP requests.
6. The client uses the refresh token when the access token expires. Tilt
   rotates refresh tokens, so store the replacement after every successful
   refresh.

The standard flow uses a public OAuth client with token endpoint authentication
method `none`. Public clients have no client secret, but the MCP endpoint still
requires an access token.

> [!NOTE]
>
> The standard external OAuth connection currently runs in the authorized
> user's personal Tilt organization. Naming another organization in a prompt
> or context reference does not change the connection's authorization. Each
> end user authorizes their own Tilt account.

Let the MCP SDK follow discovery metadata rather than hard-coding authorization
or token endpoints. A custom OAuth implementation must preserve the exact
resource through authorization and token exchange, validate callback state,
use the registered redirect URI, and store each user's credentials separately.

## Connect with an MCP client

The following TypeScript example uses the MCP SDK's Streamable HTTP transport
after OAuth has supplied an access token. Keep token acquisition and refresh in
your OAuth provider rather than embedding a token in source code.

```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import {
  StreamableHTTPClientTransport,
} from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({
  name: "example-host",
  version: "1.0.0",
});

const transport = new StreamableHTTPClientTransport(
  new URL("https://tilt.now/mcp/tilt"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${await getAccessToken()}`,
      },
    },
  },
);

await client.connect(transport);
```

Adapt the initialization to the MCP SDK and protocol version your host uses.
Configuration file formats are client-specific.

## Delegate a complete task

Call `delegate_to_agent` without `session_id` for the first turn:

```typescript theme={null}
type DelegatedRunResult = {
  run: {
    runId: string;
    sessionId: string;
    status: string;
  };
};

const result = await client.callTool({
  name: "delegate_to_agent",
  arguments: {
    message:
      "Create a US nuclear energy Tilt with 25 constituents, " +
      "exposure-proportional weighting, a 10% position cap, " +
      "and quarterly rebalancing.",
    client_time_zone: "America/Toronto",
  },
});

const { run } = result.structuredContent as DelegatedRunResult;
const { runId, sessionId } = run;
```

Persist both IDs. `runId` identifies this turn; `sessionId` identifies the
durable Tilt Agent conversation. Map the session to the same authorized user
and conversation in your application.

`delegate_to_agent` accepts the task and returns before Tilt Agent finishes.
The initial result can report `queued`, `starting`, or `running`. Receiving
the tool result does not mean the task succeeded.

## Wait for progress and consume the result

Call `wait_for_agent_run` until it returns a terminal status: `succeeded`,
`failed`, or `canceled`. Each call can wait for up to 30 seconds. Carry
`last_event_id` into the next call as `after_event_id` so that the server only
returns newer events.

```typescript theme={null}
type WaitResult = {
  status: string;
  last_event_id?: number;
  new_events?: unknown[];
};

const terminalStatuses = new Set(["succeeded", "failed", "canceled"]);
let afterEventId: number | undefined;

while (true) {
  const result = await client.callTool({
    name: "wait_for_agent_run",
    arguments: {
      run_id: runId,
      ...(afterEventId === undefined
        ? {}
        : { after_event_id: afterEventId }),
      wait_ms: 25_000,
    },
  });

  const snapshot = result.structuredContent as WaitResult;
  afterEventId = snapshot.last_event_id;

  if (terminalStatuses.has(snapshot.status)) {
    if (snapshot.status !== "succeeded") {
      throw new Error(`Tilt run ${snapshot.status}`);
    }
    break;
  }
}
```

Return each complete tool result to the orchestrating model. Tilt Agent output
uses structured UI elements with descriptive names. A model-driven MCP host can
interpret those elements and answer through its own interface. Pass the full
result rather than its status-summary text, and do not hard-code a parser for
one element type.

Carry events across every wait response when your MCP library does not preserve
the tool conversation for the model. `get_agent_run` returns the complete event
history when a client reconnects or loses its cursor.

## Choose how to present output

Choose between two presentation options:

### Let the MCP host interpret it

A model-driven host can receive the complete structured result from the run
tools. The model interprets Tilt's messages, cards, tables, and other UI elements,
then responds through the host's native interface.

### Use Tilt's MCP App

An MCP Apps-capable host can render Tilt's complete interactive experience
without mapping UI elements itself. Use the app to show Tilt cards, progress,
and follow-up interactions. Tilt can also customize the MCP App experience for
a third-party integration.

> [!NOTE]
>
> Tilt is exploring additional custom rendering options. Contact Tilt to
> discuss a specific integration.

## Continue the same Tilt Agent session

Reuse `session_id` for a follow-up after the previous run reaches a terminal
status:

```typescript theme={null}
const followUp = await client.callTool({
  name: "delegate_to_agent",
  arguments: {
    session_id: sessionId,
    message:
      "Require companies to have a market capitalization of at least " +
      "$1 billion. Keep the other rules unchanged.",
  },
});
```

Do not restate object IDs merely to recreate continuity. Tilt Agent receives
the conversation and linked Tilt context through the durable session. Only one
run can be active in a session, so serialize follow-up turns.

Creating or refining a Tilt does not publish an index. Publication remains a
separate review process.

## Handle retries and failures

Delegation can change saved Tilt state and is not idempotent. Do not
repeat `delegate_to_agent` after an ambiguous timeout. If you received the run
ID, inspect the existing run with `get_agent_run` before deciding what to do
next.

Handle three failure layers separately:

* HTTP or OAuth failures mean the connection or token could not authorize the
  request.
* JSON-RPC or tool errors do not prove that no state changed. Inspect any known
  run or session before retrying the call.
* A retrieved run with status `failed` means the delegated turn started but did
  not complete successfully; inspect its error and events.

Canceling an active run stops further work when possible; it does not roll back
changes already completed. Closing a session archives it. Do not close a
session after every turn when users may continue the conversation.

## Orchestration tools

* `delegate_to_agent` starts a run or adds a turn to an existing session. It
  changes state.
* `wait_for_agent_run` waits for new events or a terminal status. It is
  read-only.
* `get_agent_run` reads the complete current run snapshot. It is read-only.
* `get_agent_session` reads session context, transcript, and the latest-run
  summary. It is read-only.
* `cancel_agent_run` cancels an active run. It changes state.
* `close_agent_session` archives a session. It changes state.

## Host Tilt's MCP App

MCP Apps is an optional presentation layer on the same authenticated MCP
connection. Tilt advertises the `io.modelcontextprotocol/ui` extension and
associates `delegate_to_agent` with this resource:

```text theme={null}
URI: ui://tilt/session.html
MIME type: text/html;profile=mcp-app
```

An MCP Apps-capable host reads the resource through MCP, loads it in the host's
Apps environment, and supplies tool results through the Apps bridge. The app
can display run progress and Tilt cards, send follow-up user messages, request
app-only tools, and ask the host to open links.

Do not treat the `ui://` URI as a public web URL or load it directly in a
general iframe. Follow the [MCP Apps host
documentation](https://modelcontextprotocol.io/docs/extensions/apps), enforce
the resource's security metadata, and hide app-only tools from the model.

Core MCP and MCP Apps support are separate host capabilities. If a host does
not support MCP Apps, let its model interpret the complete structured run-tool
output. Use the terminal run status to determine whether the delegation
succeeded.


# Connected app views
Source: https://docs.tilt.now/tilt-agent/connected-app-views

How Tilt shows a connected app's own view in the chat, which parts of the card come from Tilt, and when Tilt asks before a view uses its app's tools.

Some apps you [connect over MCP](/tilt-agent/connect-mcp-server) send their own view along with a tool result. A view is a small interactive page that the app builds, such as a chart with buttons. YCharts is one app that offers views. Tilt shows the view in the chat, inside a card that Tilt draws around it.

The examples on this page use Sample Charts, a made-up app whose chart tool sends a view.

## When a view appears

When Tilt Agent uses a tool from a connected app and the app sends a view with the result, the chat shows a card labelled **Connected app** with the view inside. You don't need to ask for it. A tool call that fails shows no card.

| Where you read the chat | What you see |
| - | - |
| Tilt on the web or Tilt for Mac | The card with the app's view inside. |
| The same chat after you reload the page or open it again later | The same card. Tilt saves the view with the chat and draws it again. |
| A Tilt Agent session started from another app, such as Claude or ChatGPT, through Tilt's MCP server | The card with the app's name and "The view from Sample Charts can't be shown here." |
| A chat someone shared with you | The same message. Only the person who owns the chat can load its views. |

Tilt Agent can also use connected apps in a [background job](/tilt-agent/background-jobs), but a job shows no views.

## What the app draws and what Tilt draws

Everything inside the frame is the app's own page. The app decides what the page shows and what its buttons do. Tilt draws everything around the frame, so those parts always come from Tilt, whatever the app puts in its page.

![Diagram of a Connected app card titled Get economic chart, from Sample Charts (charts.example.com). Callout 1 marks the header. Callout 2 marks a dashed area labelled 'The app's own page' holding a line chart and two buttons, Show latest value and Save a note on this chart. Callout 3 marks the line 'You ran Save chart note from Sample Charts' view at 10:58 AM', which ends in a gear. Callout 4 marks the Details and Tool permissions buttons.](https://mintcdn.com/tilt/NSzk9OQDruDNFdot/images/tilt-agent/connected-app-view-parts.svg?fit=max\&auto=format\&n=NSzk9OQDruDNFdot\&q=85\&s=deb8a4c5485e6b9948f51075c2083fa6)

A diagram of a connected app's card, using a made-up app. Only the dashed area comes from the app.

| Part | Drawn by | What it tells you |
| - | - | - |
| 1. The header: **Connected app**, the tool's name, and "From Sample Charts (charts.example.com)" | Tilt | Which app sent the view. The app chooses its own name. The web address is the address of the server you connected, which the app can't change. |
| 2. The dashed area | The app | The app's own page: its chart, its numbers, and its buttons. |
| 3. "You ran Save chart note from Sample Charts' view at 10:58 AM" | Tilt | One line for each action the view ran that can change something in the app, whether or not the action succeeded. The gear at the end of the line opens the app's **Tool permissions** page at that tool and highlights it for a moment. See [When a view runs a tool](#when-a-view-runs-a-tool). |
| 4. **Details** and **Tool permissions** | Tilt | **Details** shows the app's name and web address, and the outside sites the view can reach. **Tool permissions** opens the app's **Tool permissions** page in **Settings > Connections**. |

## When a view runs a tool

A view can use its app's tools through Tilt, for example when you select a button in the view that saves a note. Tilt makes each call with your connection to the app.

Some apps keep a tool for their own view alone, such as a tool that prepares a chart download for the view's Save button. Tilt Agent never sees a tool like that, so it isn't on the app's **Tool permissions** page, and Tilt runs it right away when the view asks. The gear on its line still opens the page, which then says the tool has no setting there. If you set it to **Needs approval** or **Blocked** before the app kept it for its view, that choice still applies.

Every other tool the view uses is one Tilt Agent can use too. For those, Tilt follows the choice you set for the tool on the app's **Tool permissions** page in **Settings > Connections**, the same choice Tilt Agent follows. See [Choose what Tilt Agent may do with each tool](/tilt-agent/connect-mcp-server#choose-what-tilt-agent-may-do-with-each-tool).

| Your choice for the tool | What happens when the view uses it |
| - | - |
| **Always allow** | The call runs right away. |
| No choice, and the app labels the tool read-only | The call runs right away. |
| **Needs approval**, or no choice and the app doesn't label the tool read-only | Tilt asks you first. |
| **Blocked** | Tilt refuses the call and the view gets an error. |

A call that runs right away can run as soon as the view loads, including when Tilt draws a saved view again after you reopen the chat. The view can also read its app's data through Tilt without asking, such as the numbers behind a chart. What it reads goes only to the view.

When Tilt asks, it shows **Run a tool** over the chat. The dialog names the app and the web address of its server, as the card's header does, then the tool and each value the view wants to send. The call runs only when you select **Allow**. **Cancel**, or closing the dialog, sends nothing to the app and tells the view the call didn't run. After you turn a call down this way, or if the view withdraws the call while its dialog is open, Tilt refuses that view's later calls that need your approval, and its links and files, without asking until it draws the view again: after you reload the page, reopen the chat, or select **Reload view** or **Try again** on the card. Calls that run right away still run.

Each action that can change something in the app adds a line under the view, such as "You ran Save chart note from Sample Charts' view at 10:58 AM". Tilt records the line before the action reaches the app, so the line shows that the view ran the action, even if the action then failed. The lines stay with the chat. Actions the app marks as read-only, such as showing the latest value, add no line.

## When a view opens a link

A view can ask Tilt to open a link, such as a download link for a chart or a page on the app's own site. Tilt first shows **Open external link** over the chat. It names the app and the web address of its server, as the card's header does, then shows the site the link goes to and the whole link. Tilt writes the site's name in plain letters, so a name that hides a lookalike letter from another alphabet shows its real spelling.

The link opens only when you select **Open**: in a new tab on the web, or in your browser in Tilt for Mac. **Cancel** closes the dialog and tells the view the link didn't open. After you turn a link down this way, or by closing the dialog, or if the view withdraws a link while its dialog is open, Tilt refuses that view's later links, files and calls that need your approval without asking until it draws the view again: after you reload the page, reopen the chat, or select **Reload view** or **Try again** on the card. A button that runs one of the app's tools before it opens a link, such as a Save button that prepares a download, runs that tool first the same way as any other call from the view.

Tilt refuses, without asking, a link that isn't an ordinary web address (one that starts with http or https), a link to a Tilt site or to tiltmcpcontent.com, and a link while another of Tilt's dialogs is still waiting for you.

## When a view saves a file

A view can also hand Tilt a file to save, such as a chart image or a table as a CSV file. Tilt first shows **Download file** over the chat, or **Download files** when there are several. It names the app and the web address of its server, then lists each file with the name Tilt will save it under, the type of file the app says it is, and its size.

The files are saved only when you select **Download**, as a normal download in your browser or in Tilt for Mac. Tilt never opens a file in the page, whatever type the app says it is. A file's name keeps only its last part, without folders or hidden-file dots, so a name like `../../.zshrc` is saved as `zshrc`. **Cancel** closes the dialog and saves nothing, and after that Tilt refuses that view's later files, links and calls that need your approval without asking, the same way it does after you turn down a link.

A view can also hand Tilt a link to a file stored elsewhere. Tilt lists it with the site it goes to and the whole link, checks it the same way as any link a view sends, and opens it in a new tab when you select **Download**. Tilt's servers never fetch it. If any link in the request is one Tilt refuses, Tilt refuses the whole request without asking.

## When a view fills the screen

Some views have their own button to show a bigger version, such as an **Edit** button that opens a diagram editor. When you press it and the view asks, Tilt shows the same view over the whole Tilt window, under a bar that Tilt draws across the top. The bar shows the tool's name and "From Sample Charts (charts.example.com)", the same names as the card's header, and a **Close** button. In Tilt for Mac, the view fills the window below the title bar.

**Close** puts the view back in its card in the chat. Pressing Escape does the same when Tilt has the keyboard, for example after you click the bar. While you're typing inside the view, the view gets the key, and many views also have their own button to go back. The view also goes back to its card when you move to another part of Tilt, such as the command palette. Either way, the view keeps what you were doing, because it keeps running and doesn't load again.

A view can't fill the screen on its own: Tilt does it only right after you click or type in that view. Only one view fills the screen at a time. A view can't start filling the screen while one of Tilt's dialogs is waiting for you, and while a view fills the screen, Tilt refuses links, files and calls that need your approval from other views without asking.

Anything the view does with its app while it fills the screen follows the same rules as in the card. A link, a file or a call that needs your approval shows its dialog above the view. If the app says its view works only in the card, Tilt keeps it there.

## How Tilt keeps a view apart

* The view runs in a sandboxed frame on tiltmcpcontent.com, a separate domain that Tilt uses only for app views. Each app's views get their own address there, apart from every other app's. Because the view never runs on a Tilt domain, it can't read your Tilt cookies or sign-in, and it can't reach Tilt's servers.
* From your chat, the view gets only the request Tilt Agent sent to the app's tool and the result that came back, plus display settings such as light or dark mode, language, and time zone.
* The view can reach only the outside sites its app lists, and it can reach them as soon as it loads. **Details** shows them.
* The view can use only its own app's tools, never another app's. An app can also keep some of its tools away from its view. Tilt makes each call with your connection, so the view never sees your sign-in to the app, and each call to a tool Tilt Agent can also use follows your choice for that tool.
* The view can't open new windows or pop-ups, download files, or send the Tilt page somewhere else on its own. A link it asks Tilt to open waits for you to select **Open**, a file it asks Tilt to save waits for you to select **Download**, and a tool call that needs your approval waits for you to select **Allow**.
* When you disconnect the app, its views stop loading and can't act.

## What Tilt Agent sees

Tilt Agent reads the text and data the app returns with the result. It doesn't see the view itself, so it can tell you the numbers behind a chart but not what the chart looks like. Pictures the app sends are left out of what Tilt Agent reads.

Tilt Agent also doesn't see what you do inside a view. To ask about something you found there, tell Tilt Agent in the chat.

## Not supported yet

* A view sending a message into the chat.
* Views built only for ChatGPT's older Apps SDK format. For those apps, Tilt shows no view, and Tilt Agent answers from the app's text and data.

## If a view doesn't show

| Message on the card | What to do |
| - | - |
| "Reconnect Sample Charts in Settings to see this view again." | Open **Settings > Connections** and reconnect the app. |
| "The view from Sample Charts couldn't be loaded." | Select **Try again**. |
| "The view from Sample Charts tried to reload itself, so Tilt stopped it." | Select **Reload view**. |
| "The view from Sample Charts can't be shown here." | Open the chat in Tilt on the web or Tilt for Mac, signed in as the chat's owner. |


# Create an automation in chat
Source: https://docs.tilt.now/tilt-agent/create-automation

Ask Tilt Agent to repeat a clear assignment on a schedule.

Use **Main** to schedule recurring work and read its results. Tilt Agent saves the assignment, schedule, timezone, and output policy together. If you ask from a side chat, Tilt Agent can relay a self-contained request to Main. Include the scope and instructions Main needs without relying on the side chat's history.

To review changes when they happen instead of on a schedule, [create an event automation](/tilt-agent/review-changes-automation).

## 1. State the assignment and cadence

Say what to review, when to run it, which timezone to use, and when to post a result:

```text theme={null}
Every Monday at 9:00 AM America/Toronto, review my portfolio
for allocation drift, stale holdings data, and cash above target.

Post only if the review needs attention. Create the automation
in Main.
```

If the task, time, or timezone is ambiguous, Tilt Agent asks for the missing detail. After saving the automation, it confirms the schedule and next run.

## 2. Check the automation

Open **Automations** to inspect the saved prompt, next run, timezone, output policy, and previous runs. Use **Run now** to test the assignment before relying on its schedule.

Each occurrence runs as a separate [background job](/tilt-agent/background-jobs), starting fresh from the automation's saved instructions rather than Main's conversation. You can keep talking in Main while it works. The job reports back to Main; it does not wait for your ongoing conversation to finish before starting its work.

Select the job's row in Main or its name in the title bar to follow the live transcript. The job header links to its automation and shows the occurrence's date and time. The running-jobs menu shows current work. Open **Automations** for the full run history, including older runs.

If you ask for meaningful updates only, Tilt Agent stays quiet when nothing changes. You can still inspect a run that found nothing to report in **Automations**. For runs that produce a notification, the email can highlight findings from that run and why they need your attention.

## 3. Manage future runs

Ask Tilt Agent to change the automation in Main, or use **Edit**, **Pause**, and **Resume** on its detail page. **Pause** prevents future occurrences until you resume it. Occurrences already accepted to run can finish, even if their work has not started yet.

To end one occurrence, open its job page and select **Stop**. Stopping an occurrence leaves the schedule in place. To stop the jobs in the running-jobs menu, select **Stop all**, then **Stop all jobs?**. This targets the jobs shown when you began confirmation; jobs that start afterward are not included.


# Create a dashboard
Source: https://docs.tilt.now/tilt-agent/create-dashboard

Build a saved dashboard with Tilt Agent and reopen it from Library with current data.

A dashboard is a saved view that runs again when you open it, so it shows current data each time. This guide builds a read-only Market Session Checklist. Each run checks the time against the regular US-equities weekday session.

## 1. Ask for a dashboard

Select **New dashboard** in **Library > Dashboards** to start a request in chat, or ask Tilt Agent directly. Describe the changing data, the sections you need, and what the dashboard must not do.

```text theme={null}
Build and save a dashboard called Market Session Checklist.

Each time it runs, show whether the current time falls inside
the regular US-equities weekday session of 9:30 AM to 4:00 PM
Eastern. State that this does not confirm holidays, early closes,
or unscheduled closures. Follow it with a concise read-only
checklist for reviewing cash, allocation drift, and proposals
awaiting review. Make missing data explicit. Save it to Library.
```

![A chat request asking Tilt Agent to create and save a Market Session Checklist with a regular-session calculation and read-only review checks](https://mintcdn.com/tilt/KdlLLpRFqNhLRxbq/images/tilt-agent/create-scripted-artifact-chat.png?fit=max\&auto=format\&n=KdlLLpRFqNhLRxbq\&q=85\&s=f0af2971c6a092db8ffaba31db07afcb)

The request names the dashboard, the session-window calculation, and its limits.

Tilt Agent builds the dashboard, runs it, and checks its output before saving it. Wait for the confirmation that it was saved to Library.

## 2. Review the dashboard

Open the dashboard from the chat or from **Library > Dashboards**. Each card shows a one-line description and when the dashboard last refreshed.

![Market Session Checklist dashboard showing the regular US-equities session window and read-only checks for cash, allocation drift, and proposals awaiting review](https://mintcdn.com/tilt/KdlLLpRFqNhLRxbq/images/tilt-agent/market-open-checklist.png?fit=max\&auto=format\&n=KdlLLpRFqNhLRxbq\&q=85\&s=e6d9c4b045a22a870c3274a246774e57)

The saved dashboard reports the current market window and labels unavailable portfolio data.

The example has no connected portfolio data, so it labels each unavailable input instead of inventing a result.

## 3. Open it again

Opening a dashboard runs it again. If it ran in the last few minutes, the header shows how old the data is; select **Reload** to run it now. Use **Edit** to ask Tilt Agent to change the dashboard, or **Rename** to change its title.

Ask for another dashboard when the new view answers a different question. Keep each dashboard focused on one recurring question.

## Starters

**Library > Dashboards** also lists starters: ready-made dashboards that fit your account, such as **Advisor Dashboard** in an organization you advise. Select **Open** to add your copy. A starter leaves the list once you have opened it.


# Create a Personal Skill
Source: https://docs.tilt.now/tilt-agent/create-personal-skill

Teach Tilt Agent a reusable workflow and save it from the conversation.

A Personal Skill stores instructions, examples, and guardrails that Tilt Agent can reuse. Skills you create are visible only to you.

## 1. Describe the workflow

Start a chat and ask Tilt Agent to create and save the skill. Name the situations that should activate it, the result you expect, and any actions that require confirmation.

For an advisor review format, send:

```text theme={null}
Create and save a Personal Skill named Advisor Review Brief.

Use it whenever I ask for a client, account, or household
review. Return these sections in order: What changed,
Evidence, Recommended follow-up, and Decision needed.

Name the client and account for every finding. Mark missing
values instead of estimating them. Do not change configuration
or create a proposal without my confirmation.
```

![A chat where the user asks Tilt Agent to create Advisor Review Brief and Tilt Agent confirms that it saved the Personal Skill with the command name advisor-review-brief](https://mintcdn.com/tilt/KdlLLpRFqNhLRxbq/images/tilt-agent/create-personal-skill-chat.png?fit=max\&auto=format\&n=KdlLLpRFqNhLRxbq\&q=85\&s=e3caf8b1d49c1ab758d1472b424f1e3f)

Tilt Agent creates and saves the skill in the conversation.

## 2. Review the saved skill

Tilt Agent confirms the display name and its slash command after the save succeeds. Select **View skill** to inspect the instructions and enable or disable the skill.

You can invoke this example directly with `/advisor-review-brief`. Tilt Agent can also choose an enabled skill when your request matches its description.

## 3. Test and revise it

Try the skill with a client or test household. For example:

```text theme={null}
/advisor-review-brief Prepare a review for the Smith
household's retirement and taxable accounts.
```

Check the structure, evidence, and confirmation boundaries. Continue in chat to revise the skill when the result needs a different section, source, or safeguard.

> [card] [Import an external skill](/tilt-agent/import-personal-skill)
>
> Bring a skill folder from another source into Personal Skills.


# Import an external skill
Source: https://docs.tilt.now/tilt-agent/import-personal-skill

Import a Personal Skill, then ask Tilt Agent to adapt it for your work in Tilt.

You can import a skill from another source and ask Tilt Agent to revise it in chat. Tilt saves each revision as a new version of your Personal Skill.

## 1. Review the source

Import skills only from sources you trust. Read the instructions and any scripts before importing, especially anything that requests credentials, sends data, or changes another system.

The [Claude for Financial Advisors repository](https://github.com/anthropics/claude-for-financial-advisors) includes a `skills/pre-meeting` folder for preparing advisor meetings. It uses Claude-specific tools and agents, so it will need changes before you use it in Tilt.

## 2. Import the skill

Download the repository and compress only the `skills/pre-meeting` folder as a ZIP. The ZIP must contain `SKILL.md` at its root or inside one top-level folder. Do not compress the whole repository.

Open **Settings > Skills**, select **Import ZIP**, and choose the archive. Tilt validates the ZIP and saves the imported Personal Skill. Open it to inspect the files.

## 3. Ask Tilt Agent to adapt it

In a new chat, ask Tilt Agent to read and update the imported skill:

```text theme={null}
Read my imported Personal Skill named pre-meeting, including
its bundled files. Update it for the data and tools available
in Tilt. Keep the meeting-preparation purpose and useful output
structure. Replace instructions that depend on Claude-specific
tools, agents, connectors, or other skills. Preserve source
attribution and the requirement to confirm consequential
actions. State when requested client data is unavailable.
Validate the revised skill and save it as a new version of
pre-meeting.
```

Review the updated files in **Settings > Skills**, then try the skill with a non-sensitive example:

```text theme={null}
/pre-meeting Prepare a review with Sample Client using only
the sample portfolio summary attached to this chat. Flag
anything you cannot verify.
```

Check that the brief uses the supplied facts, flags missing information, and does not take action on the client's behalf. Personal Skills are visible only to you.


# Keyboard shortcuts in Tilt for Mac
Source: https://docs.tilt.now/tilt-agent/mac-keyboard-shortcuts

Menu and tab shortcuts in Tilt for Mac.

[Tilt for Mac](/tilt-agent/tilt-for-mac) adds these shortcuts to its menus. Choose **Help** > **Keyboard Shortcuts** (⌘/) in the app for the shortcuts that work inside Tilt pages and chats.

## App and chats

| Shortcut | Action | Menu |
| - | - | - |
| ⌘, | Open **Settings** | Tilt |
| ⌘N | Start a new chat | File |
| ⌘F | Find a chat | Go |
| ⌘K | Open the command menu | View |
| ⌘B | Show or hide the chat | View |
| ⌘Q | Quit Tilt and stop notifications | Tilt |

## Pages and tabs

| Shortcut | Action | Menu |
| - | - | - |
| ⌘1 | Open **Library** | Go |
| ⌘2 | Open **Alerts** | Go |
| ⌘3 | Open **Automations** | Go |
| ⌘\[ | Go back in the tab on screen | Go |
| ⌘] | Go forward in the tab on screen | Go |
| ⌘W | Close the tab on screen | File |
| ⌘⇧T | Reopen the last closed tab | File |
| ⌥⌘B | Hide or show your pages | View |
| ⌘⇧C | Copy the link to the page on screen | File |
| ⌘⇧W | Close the window | File |

## Tilt Capture

| Shortcut | Action |
| - | - |
| Both Shift keys | Capture the window in front of you into a chat. You can change the shortcut in **Settings** > **Tilt Capture**. |

See [Tilt Capture](/tilt-agent/tilt-capture) to set it up.


# Tilt Agent
Source: https://docs.tilt.now/tilt-agent/overview

Learn how chats, Library, Personal Skills, dashboards, and automations fit together.

Ask Tilt Agent to research, analyze, and carry out work in Tilt. Describe the outcome you need, review the result, and refine it in the same chat.

## Start with a chat

Use your Main chat for most work with Tilt Agent. Ask questions, give instructions, and follow up there as you move between pages. Opening a different page does not require a new chat.

Use another chat when an assignment needs its own ongoing conversation, such as a client review or a research question you want to revisit. Return to Main chat when you move on to other work.

Name the companies you want to research, or include the client, account, household, Tilt, or portfolio involved. Add the period, format, and limits that matter.

You can [research a company](/tilt-agent/research-company) without attaching a Tilt or portfolio. Ask about its business, a price move, or evidence for an investment thesis.

### Find and switch chats

Open **Chats** in the chat header to return to **Main chat**, find another conversation, or start a new one when you need it.

On desktop, select the list icon beside a chat's title to open **Chats**. Select the back arrow to return to your Main chat. The title names the current conversation.

On your phone, open chat over the page you are viewing. Select **Chats** or the list icon to choose a conversation, then select **Main chat** to return to it. The back arrow in the chat list returns to the conversation you were reading. Select **Close chat** to return to the page underneath.

On a Mac, [Tilt for Mac](/tilt-agent/tilt-for-mac) keeps each page you open in a tab beside the chat, and [Tilt Capture](/tilt-agent/tilt-capture) brings any window on your screen into a chat.

Switching chats leaves the page you are viewing in place. Check [**Looking at**](/tilt-agent/ask-about-page) above the message input to see which page Tilt Agent includes with your next question.

### Work across chats

Tilt Agent can create or reuse another chat to handle part of a request. The chat you are in shows **Message sent to**. The receiving chat shows **Message from**. Select the chat name in either message to open the other chat.

To keep work in the same chat without waiting for it, ask for a [background job](/tilt-agent/background-jobs).

Each chat has its own history. **Message sent to** means Tilt Agent asked the other chat to do the work. Open that chat to see whether the work is complete. Tilt Agent still asks you to approve financial actions, permanent deletion, and other changes that need your approval.

Tilt Agent can turn a successful conversation into reusable work:

| Save it as | Use it for |
| - | - |
| Personal Skill | Reuse instructions, examples, and guardrails in later chats. |
| Dashboard | Reopen a saved view that refreshes with current data. |
| Automation | Repeat an assignment in a background job on a schedule and report back to Main. |

### Archive a chat

Open a chat's menu and choose **Archive** to remove it from your chat list while preserving its transcript. To restore the chat or permanently delete it, open **Settings > Archived chats**.

## Find work in Library

**Library** contains saved Dashboards, Tilts, Posts, Files, and other items available in your workspace. Use search or choose a section when you know which item you need.

For Tilts, Library shows whether a public version exists and whether the author lists it in Marketplace. The Tilt view identifies the version you are viewing. Read [working copies and published versions](/index-construction/working-copies-and-published-versions) for the label meanings.

![Tilt Library with filters for Overview, Dashboards, Tilts, and Files, a Search Library field, and a Dashboards section with a New dashboard button](https://mintcdn.com/tilt/ReZLbojhpGU0Omne/images/tilt-agent/library-navigation.png?fit=max\&auto=format\&n=ReZLbojhpGU0Omne\&q=85\&s=bc5c2582defe7f4b6628e8e7089e885a)

Library groups saved work by type.

Select a Tilt in Library to open its Tilt view. Under **Explore in chat**, choose a suggested question or select **Ask anything** to write your own. New Chat opens with an editable draft and the Tilt attached as context. Nothing is sent until you select **Send**.

![AI Biology Infrastructure Tilt opened from Library, with Explore in chat showing three suggested questions and Ask anything](https://mintcdn.com/tilt/TnIppz46U3DAY3N6/images/tilt-agent/library-tilt-explore.png?fit=max\&auto=format\&n=TnIppz46U3DAY3N6\&q=85\&s=c856529005a6d3c70fd92aa864faf0d4)

A Tilt opened from Library, with Explore in chat open.

Select a Tilt reference in a sent chat message to open that Tilt. **Close** returns to the message you opened it from.

Depending on your workspace, Library may include **Households**. Open a household to start a chat with that household attached as context. If the section is available but empty, Tilt shows **No households found**.

## Add a guidance pack

Guidance Packs add starter prompts, workflows, and suggested automations for a type of work. Open **Settings > Guidance Packs** to see the packs available to you.

| Guidance pack | Use it for |
| - | - |
| Advisor | Work across an organization's clients, accounts, portfolios, proposals, and monitoring policies. |
| Advisor-Managed Accounts | Review an account that an advisor manages for you. Available actions depend on your linked-account access. |

## Build reusable work

> [card] [Create a Personal Skill](/tilt-agent/create-personal-skill)
>
> Teach Tilt Agent a reusable workflow in chat.

> [card] [Import an external skill](/tilt-agent/import-personal-skill)
>
> Import a trusted skill and adapt it for Tilt.

> [card] [Create a dashboard](/tilt-agent/create-dashboard)
>
> Turn a useful view into a dashboard in Library.

> [card] [Create an automation](/tilt-agent/create-automation)
>
> Ask Tilt Agent to repeat work on a schedule.

> [card] [Work with an advisor book](/advisor/advisor-chats)
>
> Organize advisor chats, prepare client reviews, and repeat useful work.

> [card] [Delegate from your app](/tilt-agent/connect-over-mcp)
>
> Delegate Tilt Agent tasks from a chat or agent experience you operate.

> [card] [Connect an MCP server](/tilt-agent/connect-mcp-server)
>
> Give Tilt Agent access to an external service's tools through an authorized connection.


# Work with pages in tabs
Source: https://docs.tilt.now/tilt-agent/page-tabs

Keep several Tilts, accounts, and other pages open in tabs beside the chat in Tilt for Mac.

In [Tilt for Mac](/tilt-agent/tilt-for-mac), every page you open gets a tab in the title bar, beside the chat. One tab shows at a time, and each tab keeps its own back and forward history. Tilt Agent sees the tab on screen and knows which others are open, so you can compare them without repeating their names.

![Tilt for Mac window with Library, Rate-sensitive housing equities, and Membership warehouse retail tabs in the title bar, the Rate-sensitive housing equities Overview on screen, and the chat on the left](https://mintcdn.com/tilt/1qTcQ_j2s2FFZ4PS/images/tilt-agent/page-tabs-window.png?fit=max\&auto=format\&n=1qTcQ_j2s2FFZ4PS\&q=85\&s=6c64420d899d6716aa63cd7e4a882613)

Library and two Tilts open in tabs, with the chat beside the Tilt on screen.

## Open pages in tabs

Open a page as you would on the web: from a card in a chat, the sidebar, a pin, or a link. The page opens in a new tab at the right end of the strip. If that page already has a tab, Tilt shows that tab.

A Tilt's views, **Overview**, **Rules**, **Portfolio**, **News**, and **History**, share one tab. Links inside a page open in the same tab; ⌘-click a link to open it in a new tab.

**Back** and **Forward** (⌘\[ and ⌘]) move through the tab on screen.

Each tab is named after what its page shows, such as the Tilt's name, or after the page itself, such as **Library** or **Alerts**. The menu at the end of the strip lists every open page and your recently closed ones. It shows as **+N** when some tabs don't fit in the title bar, and as a down arrow when they all fit and you have closed a page.

## Close and reopen tabs

| To | Do this |
| - | - |
| Close the tab on screen | Select its close button, or press ⌘W |
| Close other tabs | Right-click a tab and select **Close Other Pages** or **Close Pages to the Right** |
| Close every tab | Select **Close All Pages** in the menu at the end of the strip, or search the command menu (⌘K) for **Close all pages** |
| Reopen a closed tab | Press ⌘⇧T, or pick it under **Recently closed** in the menu at the end of the strip |

A page with unsaved changes asks before it closes. With no tabs open, the window shows the chat.

## Choose how much room the chat gets

The buttons at the right of the title bar change the layout. Hover over one to see its name and shortcut.

| Button | Shortcut | Result |
| - | - | - |
| **Hide chat** | ⌘B | The page fills the window. Select **Show chat** to bring the chat back. |
| **Hide pages** | ⌥⌘B | The chat fills the window. Your tabs wait behind a count in the title bar. Shown while the chat is open. |

Select the count to show your pages again, or hover over it to pick a tab from **Open pages**. Opening any page also shows them.

## Ask about your tabs

**Looking at** above the message input names the page in the tab on screen. When other tabs are open, **+N open tabs** beside it lists them under **Also open**; pick one to switch to it.

![Chat message input showing Looking at Rate-sensitive housing equities and +1 open tab above Ask Tilt](https://mintcdn.com/tilt/3FFJMr0s0_XQx6UT/images/tilt-agent/page-tabs-composer.png?fit=max\&auto=format\&n=3FFJMr0s0_XQx6UT\&q=85\&s=402d586e135dad9c85112f3faa908494)

Looking at names the tab on screen; +1 open tab lists the other one.

Tilt Agent receives the page on screen and the names of the objects in your other tabs with each message. Ask about them together:

> Compare this Tilt with the one in my other tab.

Pages that show no single object, such as **Library** or **Alerts**, are not included. While your pages are hidden, Tilt Agent sees no page and no open tabs.

See [Ask about the page](/tilt-agent/ask-about-page) for how **Looking at** works.

## Your tabs after a restart

Tilt reopens your tabs in order, with the same tab on screen, when you sign in again with the same account. Each tab loads when you first show it. Tabs from an organization you no longer have open stay closed. Signing in with a different account starts with no tabs.


# Questions
Source: https://docs.tilt.now/tilt-agent/questions

Give Tilt Agent the preferences it needs to move your work forward.

When a request could go in several directions, Tilt Agent can ask questions with selectable answers. Use them to choose a focus, set constraints, or decide how much detail you need.

![Tilt Agent asking which investment trend to research, with Energy and electrification selected, a Write my own answer option, and a Next button](https://mintcdn.com/tilt/CVJ4FMmJkpznQNOQ/images/tilt-agent/questions.png?fit=max\&auto=format\&n=CVJ4FMmJkpznQNOQ\&q=85\&s=426847b1303b439a2e54149a798cba8b)

Choose an answer or write your own, without leaving the chat.

## Answer in your own terms

Select the option that fits. Some questions allow multiple selections, and every question accepts a custom answer. You can also reply in the chat instead of using the card.

For a set of questions, use **Next** and **Back** to move between them. Select **Send answers** to send your choices together. Until then, you can change them.

Tilt Agent uses your answers to continue the conversation. Sending answers is a chat reply; the card itself does not save settings or execute an action.

## Ask for help deciding

Try:

> I want to research a new investment theme. Ask me a few questions to narrow it down.

Tilt Agent chooses when structured questions would help. To inspect a proposed saved change, ask for a [change review](/tilt-agent/change-reviews).


# Research a company
Source: https://docs.tilt.now/tilt-agent/research-company

Understand a business, investigate a price move, or compare companies with Tilt Agent.

Ask Tilt Agent about a public company in chat. You can use a company name or ticker without attaching a Tilt, selecting a portfolio, or connecting a brokerage account.

## 1. Ask your question

Open a chat and describe what you want to understand. For example:

```text theme={null}
Why have Micron, Credo,
and Bloom risen so much this year?
```

Include the period when it matters. You can ask in your own words; Tilt Agent finds relevant company evidence without requiring you to provide an article or choose sources.

For a different research question, try:

| Your question | Example |
| - | - |
| Understand the business | How does Costco make money, and what could hurt its growth? |
| Compare companies | Compare Costco and Walmart. How important is membership to each business? |
| Examine an investment thesis | Does the evidence support the idea that Costco's membership model protects its margins? What challenges that view? |

## 2. Check the evidence and dates

Tilt Agent uses available company evidence, including filings and earnings commentary, to explain business results, outlook, and risks. It can use news to investigate a dated event. Coverage varies by company and period.

Tilt Agent distinguishes reported results, management's expectations, and its own interpretation. Review the sources alongside the explanation and follow the citations for claims that matter to your decision.

For a price move, check the return period and the dates of the supporting evidence. A trailing-year return covers a different window from year-to-date. If Tilt Agent cannot verify the exact period you requested, it should name the period it can verify and explain the gap.

Company results and announcements can help explain a price move. They do not prove how much each event contributed to the return. Tilt Agent can give a supported business explanation even when it cannot verify an exact return or establish the cause of the whole move.

## 3. Follow up in the same chat

Use a follow-up to examine a claim or change the comparison:

```text theme={null}
Which of those explanations
has the strongest evidence?
What evidence points the other way?
```

Tilt Agent compares companies against the same question and includes contrary evidence when examining a thesis. Use follow-ups to explore those findings and the questions the sources leave unanswered.

## Investigate why a ticker was selected

If you want to understand why a ticker appears in a saved Tilt or an account, name that Tilt or account in your request. Tilt Agent needs its saved selection or account evidence to investigate that question. A company's recent results alone cannot explain why it was selected.

Start with the [Tilt view](/tilt-agent/overview#find-work-in-library) for a saved Tilt, or [advisor chats](/advisor/advisor-chats#prepare-a-client-review) for a client account review.


# Review changes with an event automation
Source: https://docs.tilt.now/tilt-agent/review-changes-automation

Ask Tilt Agent to review recorded changes and post summaries in chat.

Ask Tilt Agent to watch for changes and post summaries in chat. An event automation runs after matching changes happen.

## 1. Describe the changes and the review

Open the chat where you want the summaries. Name the changes to watch and what Tilt Agent should report. For a firm-wide review of model and sleeve settings, ask:

```text theme={null}
Whenever anyone changes model or sleeve settings in this firm,
post a summary here of which fields changed and who changed them.

Group matching events into 15-minute batches. Post after every
batch and make no changes. Create the automation in this chat.
```

## 2. Confirm the scope

Check Tilt Agent's confirmation for what it will watch, where it will post, and whether the assignment makes any changes. The example asks for a read-only review of model and sleeve settings across your firm.

For a narrower review, name the model and sleeves you want watched. Watching the Growth model includes changes to its sleeve allocations, but not changes to each sleeve's own settings. Ask Tilt Agent to confirm coverage for those sleeves too.

## 3. Read the summary alongside History

Tilt groups matching changes into batches before Tilt Agent reviews them. The default collection window is 30 minutes. The example asks for 15-minute batches; allow time for the review after that window closes.

Read the summary in the original chat. For model settings changes, open the model's [History](/advisor/see-who-changed-an-account) to compare saved before and after values.

Sleeves have no History view, and their own settings changes do not appear in the model's History. If the summary lacks details you need, ask Tilt Agent what it can verify before drawing conclusions about the change.

For a review at a fixed time instead, [create a scheduled automation](/tilt-agent/create-automation).


# Ask about any window with Tilt Capture
Source: https://docs.tilt.now/tilt-agent/tilt-capture

Press a shortcut in any app to bring a screenshot of that window into a Tilt chat.

Tilt Capture brings the window in front of you into a chat in [Tilt for Mac](/tilt-agent/tilt-for-mac). While you read a filing, a news story, or a statement in another app, press the shortcut, and Tilt adds a screenshot of that window to a chat, ready for your question.

## Turn it on

1. In Tilt for Mac, open **Settings** (⌘,) and select **Tilt Capture**.
2. Turn on **Tilt Capture** beside **This Mac**.
3. Allow the two macOS permissions Tilt Capture needs. For each, select **Allow**: System Settings opens the matching pane beside a small Tilt Capture tile. Drag the tile into the list, and the row in Tilt shows **Allowed**.

![Tilt Capture settings showing This Mac turned on with Allow both permissions below to finish setup, Allow buttons for Screen Recording and Accessibility, and Shortcut set to Both Shift keys](https://mintcdn.com/tilt/3FFJMr0s0_XQx6UT/images/tilt-agent/tilt-capture-settings.png?fit=max\&auto=format\&n=3FFJMr0s0_XQx6UT\&q=85\&s=28e6f3c0e7e72d9bded3d02e62ca4ae8)

Tilt Capture turned on, waiting for both permissions.

| Permission | What Tilt Capture uses it for |
| - | - |
| Screen Recording | Takes a picture of only the window in front when you press the shortcut. |
| Accessibility | Notices the shortcut and reads the text in that window, including text scrolled out of view. |

When both are allowed, the setting reads **Ready**. Choose a different **Shortcut** there if you like: **Both Shift keys** (the default), **Both Option keys**, or **Both Command keys**.

## Capture a window

1. Bring the window you want to ask about to the front.
2. Press both Shift keys, or the shortcut you chose.
3. Tilt opens a chat with the screenshot attached. If the message input is empty, Tilt fills in "What does this mean for my portfolio?" Edit the question, then send it.

Tilt adds the capture to the chat you used in the last minute. Otherwise it opens a new chat.

Pressing the shortcut while Tilt is in front puts the cursor in the chat's message input. Tilt Capture never captures Tilt's own windows. If a permission is missing, the shortcut opens the **Tilt Capture** settings.

## What Tilt receives

A capture holds the screenshot of that one window, the text the window contains, and, when the app exposes it, the address of the page shown. Other windows and the rest of your screen are left out. Tilt uploads the capture as it adds it to the message input, as it does any image you attach, and Tilt Agent reads it when you send the message. To leave it out, remove the attachment before you send.

To stop capturing, turn off **Tilt Capture** in Settings. To remove the permissions, open System Settings > Privacy & Security and turn off Tilt Capture under **Screen Recording** and **Accessibility**.


# Get Tilt for Mac
Source: https://docs.tilt.now/tilt-agent/tilt-for-mac

Install Tilt for Mac, sign in, and learn what the Mac app adds to Tilt on the web.

Tilt for Mac is the Tilt app for Macs with Apple silicon. It shows the same Tilt you use on the web, with your chats, Library, and settings, and adds:

| Feature | What it does |
| - | - |
| [Page tabs](/tilt-agent/page-tabs) | Every page you open keeps a tab beside the chat. Tilt Agent sees the tab on screen and knows which others are open. |
| [Tilt Capture](/tilt-agent/tilt-capture) | A keyboard shortcut puts a screenshot of the window in front of you into a chat, so you can ask Tilt about anything on your screen. |
| Notifications | Alerts can notify your Mac while Tilt is running. |
| [Keyboard shortcuts](/tilt-agent/mac-keyboard-shortcuts) | Menu shortcuts move between chats, pages, and tabs. |

## Install and sign in

1. Download the installer from [app.tilt.io/download/mac](https://app.tilt.io/download/mac).
2. Open the downloaded file and drag **Tilt** into your Applications folder, then open it.
3. Select **Continue in browser**. Your browser opens **Sign in to Tilt for Mac**.
4. Sign in with your Tilt account, or confirm the account you are already signed in to, and select **Open Tilt**. The Mac app opens signed in.

Tilt for Mac keeps its own session. Signing out on the web leaves the Mac app signed in, and the reverse.

## Turn on notifications

Open **Settings** (⌘,), select **Alerts**, and under **Desktop notifications** select **Enable** beside **This device**. Tilt shows a test notification. If macOS asks, allow notifications from Tilt; you can change this later in System Settings > Notifications.

Selecting a notification opens what it is about in Tilt. Notifications arrive while Tilt is running: closing the window keeps Tilt running, and quitting Tilt (⌘Q) stops them.

## Updates

Tilt downloads updates in the background. When one is ready, Tilt offers **Restart to update**; select **Later** to install it the next time you quit. To check yourself, choose **Tilt** > **Check for Updates…**.

## Links

Links to other websites open in your default browser.

To copy the address of the page you are viewing, choose **File** > **Copy Page Link** (⌘⇧C) or right-click the page and select **Copy Page Link**. The link reopens the page for you on the web or in Tilt for Mac. It gives no one else access; to share a conversation, use **Share chat**.