> For the complete documentation index, see [llms.txt](https://docs.lleverage.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lleverage.ai/run-operations/overview/live-widgets.md).

# Live widgets

Put figures from a connected system or a Data Table on a Project dashboard. The Agent builds the widget, and the widget reads its source when people open the page.

A live widget is a dashboard widget that reads its figures straight from a source: a [Table](https://docs.lleverage.ai/build-and-improve/intelligence/tables.md) in the Project, or a system the Agent can connect to. Ask the Agent for "invoices waiting for approval, by approver" or "open sales orders per customer" and it builds the widget and puts it on the Overview. Nobody has to copy the data into Lleverage first.

A live widget only reads. It never changes anything in the system it reads from.

## What a live widget can read

* **A Table** in the Project.
* **A native integration**, through one of its read actions. Read actions work as a source for Microsoft Dynamics 365 Business Central, Microsoft Dynamics 365 Finance & Operations, Dynamics NAV, SAP S/4HANA, AccountView, Gmail, Outlook, Microsoft Outlook Calendar, Microsoft Teams, Sharepoint, Microsoft Excel, Microsoft OneDrive, Google Sheets, Google Drive, Google Docs, Google Calendar, Google BigQuery, Slack, Notion, Jira, Confluence, Zendesk, Zoho CRM and Typeform.
* **A** [**custom integration**](https://docs.lleverage.ai/build-and-improve/overview/custom-integrations.md), such as a Ridder iQ connection, when the request only reads data (a GET or HEAD request).

### Which connections a widget can use

Everyone who opens the dashboard sees the widget's figures, so a widget reads through a connection that belongs to the Project, not to one person. The connection must be:

* a shared connection, not a personal one;
* available to Workflows;
* active;
* open to every role, not restricted to some;
* allowed to run the action without approval. A widget reads with nobody there to approve the call.

When no connection fits, the Agent tells you which one to share with the Project. See [Connections](https://docs.lleverage.ai/administer-and-govern/control/connections.md) for shared and personal connections.

## Add a live widget

Builders add and change live widgets. Operators see them on the dashboard like any other widget.

### Ask the Agent

Describe the figure you want, for example:

> Add a widget to the Overview with the invoices waiting for approval this month, per approver.

The Agent then:

1. finds a source: a Table first, otherwise a read action on a connected system;
2. picks a shared connection that may run that action;
3. previews the figures, and narrows the request until it fits what a widget can hold;
4. chooses a stat card, bar chart, line chart or table, creates the widget and places it on the Overview;
5. tells you how often the widget refreshes and whether it can be incomplete.

Say which period you want, such as "this month" or "the last 28 days". The widget then always shows that period.

### Add a widget from the page

1. On the page, type `/` on an empty line, or choose **+** beside a block.
2. Under **Dashboarding**, choose a chart, such as **Bar chart** or **Number**.
3. Click the card that appears and choose **Live data**.
4. The Agent opens beside the page in a new conversation with the widget attached. Tell it what the widget should show. Until it has built the widget, the card shows **Building with agent**.

**Live widget** is offered on the Overview and custom pages in [Pages](https://docs.lleverage.ai/run-operations/overview/pages.md) only.

### Change a live widget

A live widget is defined as code, so you change it through the Agent. Click the widget's handle and choose **Edit with AI**, or choose **Settings** and then **Chat with agent**. Either opens a new Agent conversation with that widget attached. Ask for the change in plain words, such as "make this a bar chart" or "split it by status".

The widget's settings show its **Title**, **Source**, **Chart** and **Refreshes every**. You can read them there but not edit them.

A change to the chart only keeps the figures already read. A change to the source, the shape of the data or the period makes the widget read its source again.

**Edit with AI** and **Chat with agent** are not available on a phone.

## How the figures stay fresh

Each widget keeps its last result for a set time, shown as **Refreshes every** in its settings. The Agent sets it when it builds the widget, usually to 5 minutes for Tables and most systems and to 15 minutes for slow ones. Ask the Agent if you want a different interval; it can be anything from 1 minute to 24 hours.

* **Within that time**, the page shows the kept result straight away. Everyone who opens the page shares it, so the source is read once per interval, not once per viewer.
* **After that time**, opening the page makes the widget read its source again. The last figures stay on screen while it reads, then update.
* **While the page stays open**, nothing updates by itself. Use the refresh button on a widget to read that widget again, or **Refresh live data** at the top of the page to read every live widget on it.

Each widget shows when it last read its source, such as "3 minutes ago". When that is longer ago than its refresh interval, the widget's refresh button stands out.

A widget that has figures keeps showing them if a read fails. The error appears under the chart, beside the last good figures, for example "The source couldn't be read. It will be tried again." When a connection needs attention, **Manage connections** under the widget takes you to the Project's connections. A widget only has no figures to show before its first read has finished, or when that first read fails.

## What runs behind a widget

A live widget has no schedule and no Agent behind it. It reads its source only when someone opens the page after the refresh interval, or presses refresh. That read is a single call to the source, run in the background:

* it does not start an Agent session, so it never appears in your session list;
* it is not recorded in Monitoring.

If you need figures collected on a schedule, or a history the source system does not keep, ask the Agent to build a scheduled Workflow that writes the data into a Table, then point the widget at that Table. Those Workflow runs appear in [Monitoring](https://docs.lleverage.ai/build-and-improve/monitoring.md) like any other run.

## Who sees the figures

Everyone who can open the dashboard sees the same figures, read through the widget's shared connection. A widget on a Table only shows its figures to people who may read that Table. Others see "You don't have access to this widget's source."

## Limits

Each read is one call, without paging through further results:

* A widget on a Table reads at most 500 records, or 500 groups when it counts or adds up.
* A widget on a connected system reads one response of at most 64 KB. The Agent asks only for the fields the chart needs and caps the number of records to stay under that.

When a widget may not hold everything, it says so next to its source under the chart:

* **Showing the first ... records** means the source has more records than the widget read.
* **May not include everything** means the source cannot confirm that it returned everything. Widgets on a custom integration always show this.

A page loads up to 64 live widgets at once. Move any more to another page.

Very large data sets and long histories do not fit in one read. Keep them in a Table filled by a scheduled Workflow, as described above. Syncing an ERP straight into a Table is planned for later.

Live widgets do not load in an archived Project.

## Related pages

* [Project overview](https://docs.lleverage.ai/run-operations/overview/project-dashboard.md): generated and custom Overviews.
* [Monitoring](https://docs.lleverage.ai/build-and-improve/monitoring.md): dashboards in saved views built from Tables, and Activity.
* [Connections](https://docs.lleverage.ai/administer-and-govern/control/connections.md): shared and personal connections.
* [Custom integrations](https://docs.lleverage.ai/build-and-improve/overview/custom-integrations.md): connect a system that has no native integration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lleverage.ai/run-operations/overview/live-widgets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
