# uip insights filter-folders

> Syntax and options for `uip insights filter-folders`, which discovers folders with recent Insights activity for use with --folder-key filters.

`uip insights filter-folders` discovers folders that have had Insights activity recently, restricted to folders the current caller can access. Use it to find the `--folder-key` values that [jobs](./uip-insights-jobs.md) and other Insights filters accept.

:::note
"Recent" is a fixed **30-day** window set by the backend — it cannot be changed with a flag. This route is also feature-gated to Cloud and Dedicated SaaS deployments; on other deployment types the command fails with a `ConfigError` rather than an empty result.
:::

## Synopsis

```text
uip insights filter-folders list [-l <n>] [-o <n>]
```

This verb honors the [global options](./global-options.md) and the standard [exit codes](./exit-codes.md). It does not accept `-t, --tenant` — it uses the tenant selected during `uip login`.

## uip insights filter-folders list

List folders with Insights activity in the backend's fixed 30-day window.

### Options

| Flag | Description |
|---|---|
| `-l, --limit <number>` | Maximum rows to return. Defaults to `50`. |
| `-o, --offset <number>` | Rows to skip before returning results. |

Rows are deduplicated and sorted after fetching — the backend returns one entry per underlying activity record, not one per distinct folder, so pagination is over the distinct set, not raw activity records. Pagination itself is client-side, over the full unpaginated backend response.

### Example

```bash
uip insights filter-folders list
```

### Data shape

```json
{
  "Code": "InsightsFilterFoldersList",
  "Data": [
    {
      "folderName": "Finance/Invoicing",
      "folderKey": "f0f0f0f0-0000-0000-0000-000000000001"
    }
  ],
  "Pagination": { "Returned": 1, "Limit": 50, "Offset": 0, "Total": 1, "HasMore": false }
}
```

`folderName` carries the full folder path, matching the Insights UI's folder picker. An empty `Data` array means no matching activity in the 30-day window for the current caller — it is not proof the folder doesn't exist.

## Related

- [jobs](./uip-insights-jobs.md) — accepts `--folder-key` values discovered here.
- [filter-processes](./uip-insights-filter-processes.md), [filter-machines](./uip-insights-filter-machines.md), [filter-queues](./uip-insights-filter-queues.md) — sibling discovery commands.

## See also

- [Insights overview](./uip-insights.md)