> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List Storage Batches

> List batch windows and their exact agent_state_id/run linkage. folder_id matches the stable Drive/Dropbox batch folder identity. batch_key can select S3 or older path-based batches.

Required scope: `triggers:read`. See [API key permissions](/api/api-key-scopes) and the [pipeline dashboard guide](/api/observability/overview).

## Request

```bash theme={null}
curl "https://api.mosaic.so/storage_batches?limit=25" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "X-Workspace-Id: 66666666-6666-4666-8666-666666666666"
```

Workspace IDs and resource IDs above are examples. Use IDs returned by your own API calls.

## Parameters

| Parameter | Location | Meaning |
| - | - | - |
| `limit` | query | Page size from 1 to 100; default 25. Progress and notification configuration pages count tiles. |
| `cursor` | query | Opaque next\_cursor from the previous page. Pass verbatim and preserve the original filters. Do not decode or construct it. |
| `from` | query | Inclusive ISO 8601 lower bound on creation time. |
| `to` | query | Inclusive ISO 8601 upper bound on creation time. |
| `updated_from` | query | Inclusive ISO 8601 update watermark. Restart pagination on each poll and fetch every page before advancing it. |
| `workspace_id` | query | Optional workspace UUID within the key organization. Must match X-Workspace-Id when both are supplied. |
| `trigger_id` | query | trigger id UUID. |
| `agent_id` | query | Originating agent UUID. |
| `folder_id` | query | Provider parent folder ID for event/folder queries; batches use batch\_folder\_node\_id. |
| `batch_key` | query | Exact grouping key. |
| `status` | query | Exact persisted status; for example pending for events or open for batches. |
| `X-Workspace-Id` | header | Restrict requests to an authorized workspace UUID. Omit to query the organization. |

## Response example

```json theme={null}
{
  "batches": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "storage_trigger_subscription_id": "22222222-2222-4222-8222-222222222222",
      "agent_id": "11111111-1111-4111-8111-111111111111",
      "batch_key": "production-7",
      "batch_folder_node_id": "drive-folder-7",
      "status": "flushed",
      "opened_at": "2026-10-15T12:00:00Z",
      "last_event_at": "2026-10-15T12:00:00Z",
      "scheduled_flush_at": "2026-10-15T12:01:00Z",
      "asset_count": 2,
      "created_at": "2026-10-15T12:00:00Z",
      "updated_at": "2026-10-15T12:01:00Z",
      "agent_state_id": "44444444-4444-4444-8444-444444444444",
      "retry_count": 0,
      "last_error": null,
      "error_message": null,
      "stage": "processing",
      "run": {
        "id": "44444444-4444-4444-8444-444444444444",
        "agent_id": "11111111-1111-4111-8111-111111111111",
        "workspace_id": "66666666-6666-4666-8666-666666666666",
        "status": "running",
        "status_message": null,
        "created_at": "2026-10-15T12:00:00Z",
        "updated_at": "2026-10-15T12:01:00Z",
        "trigger_info": {
          "source_folder_id": "drive-folder-7",
          "batch_window_id": "33333333-3333-4333-8333-333333333333",
          "storage_trigger_subscription_id": "22222222-2222-4222-8222-222222222222"
        }
      }
    }
  ],
  "next_cursor": null
}
```

## Batches values

| Field | Meaning |
| - | - |
| `id` | Batch window ID; use as batch\_id in item requests and run filters. |
| `storage_trigger_subscription_id` | Originating storage trigger ID. |
| `agent_id` | Originating agent ID. |
| `agent_state_id` | Exact linked run ID; null until a run is linked. |
| `batch_key` | Batch grouping key; preserve it verbatim in filters. |
| `batch_folder_node_id` | Stable batching folder identifier. This is the folder\_id accepted by the batches endpoint; it may differ from a provider parent folder ID. |
| `status` | Persisted batch status, such as open, flushing, flushed, cancelled, or failed. |
| `stage` | Dashboard stage derived from persisted batch and linked run state; never implies Slack delivery. |
| `asset_count` | Recorded asset count. |
| `retry_count` | Batch retry count. |
| `last_error` | Most recent batch error. |
| `error_message` | Batch error details. |
| `opened_at` | When the batch window opened. |
| `last_event_at` | Last observed event in this batch. |
| `scheduled_flush_at` | Earliest scheduled flush time; this is not a run completion estimate. |
| `created_at` | Batch creation time. |
| `updated_at` | Batch update time. |
| `run` | See nested schema in the API reference. |

When `next_cursor` is non-null, request the next page with the same filters and that cursor. `limit` defaults to 25 and is capped at 100. Read the [polling and error-handling guidance](/api/observability/overview#poll-without-losing-updates) before building a dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.