# Widgets

> A widget is one tile on a dashboard: a type plus the data it draws. Add one from the gallery, bind it to a workflow or market data, see where its numbers came from, or pin one from Chat.

Source: https://orbitalaip.com/docs/dashboards/widgets

## What a widget is

A widget is one tile on a dashboard. Its type decides how the tile draws, and its binding decides what data it draws: a workflow output, a built-in source such as market data, or a metric history. **Price Chart**, **Live Price** and **Live Metric** stream their own data instead.

A dashboard holds at most 60 widgets.

## Add a widget

1. **Click Add Widget**
   
   It sits in the dashboard header, and an empty dashboard also shows **Add your first widget**.

2. **Pick a widget type**
   
   Type in **Search widgets…**, or narrow the gallery with the **All widgets**, **Market data** and **Workflow-first** tabs and the category chips.

3. **Bind its data**
   
   Beside the preview sit **Title**, the data settings (**DATA SOURCE** for most types), **DISPLAY** and **ADVANCED**. A chip above the preview names what it shows: **SAMPLE DATA**, example data shown until you bind a source, **LATEST RUN** with the run's age, or **● LIVE**.

4. **Click Add to Dashboard**
   
   The tile lands at the bottom of the grid. If **Title** is empty, the widget takes the type's name.

Anyone in the project except a viewer can add or change a widget, use in-tile controls and click the screener's **Save**. See [Project roles](https://orbitalaip.com/docs/workspace-and-account/members-and-roles#project-roles).

## Gallery badges

Each gallery tile carries a badge. Hover it for its reason.

| Badge | Meaning |
| --- | --- |
| LIVE | The widget streams its own data. |
| MARKET DATA | It works at once from built-in market data. |
| NEEDS SETUP | Its built-in data needs a connection that is not set up, such as Unusual Whales options data. |
| WORKFLOW | It needs a workflow run to produce its data. |

## Data sources

Every type except the three live ones has one **DATA SOURCE** picker, filtered with **Search sources…**. It lists every source, with what fits the chosen type first, in the shelves **Your workflows**, **Market data**, **Metrics**, **Your workflows (not run yet)** and **Other sources**. The built-in source the widget is designed for is marked **RECOMMENDED**, and a source that needs setup says why.

A built-in source's settings, such as how many bars to fetch, appear under the picker and save as the widget's defaults.

Symbol-based built-in sources follow the dashboard's active symbol. When the dashboard has none, a **PREVIEW SYMBOL** field feeds the preview only. A source whose connection is not set up shows **Connection required** in the preview.

The live types follow the active symbol and have no picker. **Live Metric** also needs a **METRIC**: pick one in **Pick a metric…**, or choose **Custom metric id…** and type one.

**Agent Output** shows the newest result an agent filed in the **Library**, and refills after the agent's next run. To place one on a dashboard:

1. **Click Add to a board**
   
   It is on the output in the **Library**, and on the agent's run.

2. **Pick an existing dashboard**
   
   Choosing **New dashboard…** stops with **Pick an existing board**.

## Bind a workflow

A workflow row shows the output's name, then the workflow's name in brackets. Outputs are named in the workflow; see [Outputs, alerts and actions](https://orbitalaip.com/docs/workflows/outputs-alerts-and-actions).

The widget renders that output from the newest finished run that produced it. Orbital maps the output's fields onto the widget; adjust them under **DISPLAY**, with more behind **More options**. A few mappings, such as a **Scatter Plot**'s size and group fields, sit under **ADVANCED**. If the data does not fit the widget, a note under the picker says so.

If the workflow has not produced the output yet, the preview reads **Waiting for data**. **Run workflow now** starts a run, using the workflow's [main](https://orbitalaip.com/docs/workflows/runs-and-versions#main) version when there is one, and the preview fills in when it finishes. You can also add the widget now; it fills in after the first run.

**ADVANCED** also holds **Data extraction**:

- **Extract path** is a dot-path applied to the output before it renders, such as `results.{{symbol}}.summary`, where `{{symbol}}` stands for the active symbol.

- **Context match input path**, such as `inputs.symbol`, is the run input matched against the active symbol. The tile then shows the run made for that symbol.

On the dashboard, a workflow tile's footer shows **as of** and the age of its run, and changes colour once the run is more than 24 hours old. The arrow beside it, **Re-run**, runs the workflow again.

When the newest run cannot supply the output, the tile keeps the last good one. A header badge says why: **Updating**, **Awaiting approval**, **Paused**, **Latest failed** or **Previous output**.

A tile with nothing to show says why:

| The tile says | What it means |
| --- | --- |
| AI analysis hasn't run yet | The workflow has not run. The button runs it for the active symbol, such as Run NVDA analysis, or opens the workflow. |
| No published data yet | The source has returned nothing yet. A workflow tile offers to run or open the workflow. |
| No NVDA result was found. | No finished run covers the active symbol. The button runs it for that symbol, adds the symbol to the workflow's watchlist, or re-runs the workflow. |
| Analysis is awaiting approval, Analysis is paused | The run is waiting. Open the workflow to approve or resume it. |
| Analysis failed | The run failed. Hover the line for the error. |
| Massive data unavailable | A built-in source failed, named by its provider. Click Retry when it is offered. |
| Choose a ticker | The source needs a symbol. Pick one in the symbol sidebar. |

## Filters and views

A dashboard has no filter bar and no saved views. Tiles follow the active symbol you pick in the symbol sidebar; see [The symbol sidebar](https://orbitalaip.com/docs/dashboards/overview#the-symbol-sidebar).

Some tiles have time controls in their header, such as a period switch or range presets from **1W** to **2Y**. On a narrow tile or screen, or when a tile has more than two, they fold behind a calendar button, **Time controls**. They change only your view, and the reset arrow returns the tile to its saved settings. Controls drawn inside a widget, such as the range buttons on a **Line Chart** or **Price Chart**, save with the widget for everyone.

The **Stock Screener** keeps its filter chips, column presets and other settings inside its tile. Your changes are yours alone until you click **Save**, and the undo arrow beside it discards them.

## Change a widget

1. **Click Edit, or press E**
   
   The tiles gain their edit buttons.

2. **Click Edit widget settings**
   
   It is the gear button on the tile. The builder opens with the widget's settings. **Change type** returns to the gallery and keeps the display settings both types share.

3. **Click Save changes**
   
   

To duplicate, move or remove tiles, see [Layout and editing](https://orbitalaip.com/docs/dashboards/overview#layout-and-editing).

## Provenance: where a number came from

Outside edit mode, a tile bound to a workflow run or a built-in source has an i button in its header, **Inspect source**. It opens the **Provenance** panel.

**SOURCE** names the provider and source, or the workflow and run, with their timing. A built-in source adds **EFFECTIVE PARAMETERS**, the exact settings of the fetch. A failed fetch adds **Source error**, and a failed run **Run error**. For a workflow, **Full run record** expands to the whole run as JSON, and **Open workflow** opens the workflow, where its run history is.

Chips in a tile's header say what its data is:

| Chip | Meaning |
| --- | --- |
| NVDA, with a link icon | The widget follows the dashboard's active symbol. |
| AI | A model wrote at least part of the content, such as an agent step in the workflow. |
| watchlist-wide | The output covers the workflow's whole universe, not the selected symbol. |
| older run | The run did not record which symbols it covered, so it may not include the active symbol. Re-run the workflow. |
| Cached | The latest refresh failed, so the tile shows cached data. |
| Error | The source failed or the widget could not draw. Hover the chip for the full message. |

## Pin a chart from Chat

A chart Chat draws in a thread is marked **displayed, not saved**. To keep it as a widget:

1. **Click Pin to dashboard →**
   
   It sits under the chart and opens the **Pin to dashboard** dialog.

2. **Pick a dashboard**
   
   **New dashboard…** instead asks Chat for a new board with the chart on it.

3. **Apply the proposal**
   
   Chat answers with a proposal card, headed **PROPOSED WIDGET** for an existing dashboard. Click **Apply** to add the widget, or **Discard**. Nothing is saved before you apply.

An applied card links **View on dashboard →** and offers **Revert**. See [Proposals and approvals](https://orbitalaip.com/docs/chat/proposals-and-approvals).

An answer table can become a widget too. **Pin as widget →** appears when every value in the table comes from one built-in source. The tile is a **Data Table**, or a **Stock Screener** for a screen, and it keeps recomputing from that source. Any other table reads **Not pinnable as a widget**, with the reason. See [Asking about markets](https://orbitalaip.com/docs/chat/asking-about-markets).

Charts and tables you can pin

- "Show me a daily price chart for NVDA."
- "Screen for US stocks with a market cap over $2B and relative volume above 3."