---
title: "List Storage Batches"
method: GET
path: "/storage_batches"
tags: ["Pipeline Observability"]
---

# List Storage Batches

`GET /storage_batches`

## Request

- Base URL: `https://api.mosaic.so`
- URL: `https://api.mosaic.so/storage_batches`
- Auth: HTTP bearer

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.

## Query parameters

- `limit` integer
- `cursor` string
- `from` string, date-time
- `to` string, date-time
- `updated_from` string, date-time
- `workspace_id` string, uuid
- `trigger_id` string, uuid
- `agent_id` string, uuid
- `folder_id` string
- `batch_key` string
- `status` string

## Headers

- `X-Workspace-Id` string, uuid

## Response `200`

Current organization-scoped evidence.

- object
  - `batches` CanvasStorageBatch[]
    - `id` string, uuid, required: Batch window ID; use as batch_id in item requests and run filters.
    - `storage_trigger_subscription_id` string, uuid, required: Originating storage trigger ID.
    - `agent_id` string, uuid, required: Originating agent ID.
    - `agent_state_id` string, uuid, nullable, required: Exact linked run ID; null until a run is linked.
    - `batch_key` string, required: Batch grouping key; preserve it verbatim in filters.
    - `batch_folder_node_id` string, nullable, required: Stable batching folder identifier. This is the folder_id accepted by the batches endpoint; it may differ from a provider parent folder ID.
    - `status` string, required: Persisted batch status, such as open, flushing, flushed, cancelled, or failed.
    - `stage` 'waiting_on_processing' | 'processing' | 'processing_finished' | 'failed_before_run' | 'failed' | 'cancelled_before_run' | 'cancelled' | 'run_unavailable', required: Dashboard stage derived from persisted batch and linked run state; never implies Slack delivery.
    - `asset_count` integer, required: Recorded asset count.
    - `retry_count` integer, required: Batch retry count.
    - `last_error` string, nullable, required: Most recent batch error.
    - `error_message` string, nullable, required: Batch error details.
    - `opened_at` string, date-time, nullable, required: When the batch window opened.
    - `last_event_at` string, date-time, nullable, required: Last observed event in this batch.
    - `scheduled_flush_at` string, date-time, nullable, required: Earliest scheduled flush time; this is not a run completion estimate.
    - `created_at` string, date-time, nullable, required: Batch creation time.
    - `updated_at` string, date-time, nullable, required: Batch update time.
    - `run` CanvasRunEvidence, required
      - `id` string, uuid, required: Run ID; use as run_id in run endpoints.
      - `agent_id` string, uuid, nullable, required: Originating agent ID.
      - `workspace_id` string, uuid, required: Workspace that owns this run.
      - `status` string, required: Persisted run status, such as queued, running, completed, partial_complete, failed, or cancelled.
      - `status_message` string, nullable, required: Run status details.
      - `created_at` string, date-time, required: Run creation time.
      - `updated_at` string, date-time, nullable, required: Last run-row update; null for unchanged historical runs. Node/task changes can happen independently.
      - `trigger_info` object, nullable, required: Source metadata, including source_folder_id, batch_window_id, batch_key, storage_trigger_subscription_id, or production_id when supplied by the trigger.
  - `next_cursor` string, nullable: Opaque cursor for the next page; null at the end.

## 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)