---
title: "List Watched Folders"
method: GET
path: "/storage_trigger/{trigger_id}/folders"
tags: ["Pipeline Observability"]
---

# List Watched Folders

`GET /storage_trigger/{trigger_id}/folders`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/storage_trigger/{trigger_id}/folders`
- Auth: HTTP bearer

List discovered watched Drive/Dropbox folders, watcher health, last observed event, and errors. Empty last_event_at means no recorded event; it does not prove that a folder contains no files.

## Path parameters

- `trigger_id` string, uuid, required

## Query parameters

- `limit` integer
- `cursor` string
- `from` string, date-time
- `to` string, date-time
- `updated_from` string, date-time
- `workspace_id` string, uuid
- `folder_id` string
- `active` boolean

## Headers

- `X-Workspace-Id` string, uuid

## Response `200`

Current organization-scoped evidence.

- object
  - `folders` CanvasWatchedFolder[]
    - `id` string, uuid, required: Watcher subscription ID, used internally by pagination.
    - `created_at` string, date-time, required: Watcher subscription creation time.
    - `updated_at` string, date-time, required: Later of subscription.updated_at and watcher.updated_at. updated_from matches either row.
    - `depth_from_root` integer, required: Folder depth below the selected root.
    - `is_active` boolean, required: Whether this trigger currently watches this folder.
    - `watcher` object, required
      - `id` string, uuid, required: Shared watcher ID.
      - `folder_id` string, required: Provider folder ID. Use this value for the events endpoint folder_id filter.
      - `folder_name` string, nullable, required: Current folder name from the cache.
      - `status` string, required: Persisted watcher health; inspect last_error when unhealthy.
      - `last_event_at` string, date-time, nullable, required: Last recorded storage event. Null means no recorded event, not proof the folder is empty.
      - `last_error` string, nullable, required: Last watcher or recovery error.
      - `webhook_interval_minutes` integer, required: Configured watcher interval.
      - `updated_at` string, date-time, required: Watcher row update time.
      - `deleted_at` string, date-time, nullable, required: Soft-deletion time. Deleted watchers remain visible for diagnostics.
  - `next_cursor` string, nullable: Opaque cursor for the next page; null at the end.
  - `trigger_id` string, uuid: Requested storage trigger ID.

## Other responses

- `400`: Invalid UUID, cursor, limit, timestamp, filter, or unsupported updated_from on batch items.
- `401`: Missing, invalid, or revoked API key.
- `403`: Insufficient API key scope, unavailable paid-plan access, or workspace header/query mismatch. Scope errors include code, required_scope, granted_scopes, retryable, and resolution. Other authorization errors retain detail.
- `404`: Requested run, trigger, or batch is absent or outside the authorized organization/workspace.
- `500`: Database or query failure. Never interpret this as an empty successful result; use bounded backoff.

---

[API](https://skmtc.dev/mosaic/apis/mosaic-ai-api.md) - [All operations](https://skmtc.dev/mosaic/apis/mosaic-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mosaic/apis/mosaic-ai-api/revisions/c20e9fc606a4?raw)