---
title: "List upload batches"
method: GET
path: "/api/v1/external/upload-batches"
tags: ["Upload Batches"]
---

# List upload batches

`GET /api/v1/external/upload-batches`

## Request

- Base URL: `https://api.wove.com`
- URL: `https://api.wove.com/api/v1/external/upload-batches`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/wove/apis/wove-external-api/docs/api/v1/external/upload-batches/get.ts> (a function with typed inputs; its response is checked against the schema)

List your organization's most recent upload batches, newest first. Only batches whose object types
you can read are returned.

**Required scopes:** `documents:read`, plus the read scope of a batch's object types
(`shipments:read` or `customs:read`; `shipments:read` for unrestricted batches).

## Query parameters

- `limit` integer

## Response `200`

Upload batches retrieved successfully

- object
  - `success` boolean
  - `data` object
    - `batches` UploadBatch[]
      - `id` string, required
      - `label` string, nullable
      - `note` string, nullable: Free-text context supplied with the upload
      - `entryType` '01' | '11' | 'export' | 'in_bond' | 'ca_b3' | 'ca_clvs' | 'ca_type_f' | 'null', nullable: Customs entry type hint. Customs-entry batches only.
      - `filingCountry` string, nullable: ISO-2 filing country hint. Customs-entry batches only.
      - `status` 'pending' | 'processing' | 'completed' | 'failed', required
      - `branchId` string, nullable
      - `documentCount` integer, required: Documents created from the files, after zip expansion and splitting
      - `sourceFileCount` integer: Files received, after zip expansion
      - `duplicateFileCount` integer: Files skipped because identical content was already ingested for this batch
      - `createdEntities` UploadBatchCreatedEntity[], required: Entities the pipeline created or attached to. Empty until the batch completes.
        - `entityType` string, required: Type of entity the batch produced
        - `entityId` string, required
        - `documentIds` string[], required: Documents from the batch attached to this entity
        - `isNew` boolean: False when the documents were attached to an entity that already existed (e.g. a shipment matched on its bill of lading). Absent on older batches.
      - `unusedDocumentIds` string[], required: Documents the pipeline could not tie to any entity
      - `error` string, nullable: Failure reason when status is failed
      - `processedAt` string, date-time, nullable
      - `createdAt` string, date-time, required
      - `externalShipmentRefId` string, nullable: TMS job the documents were imported from. Null for file uploads.
      - `tmsSource` string, nullable: TMS the documents were imported from. Null for file uploads.

## Other responses

- `401`: Authentication required or invalid credentials
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/wove/apis/wove-external-api.md) - [All operations](https://skmtc.dev/wove/apis/wove-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wove/apis/wove-external-api/revisions/37290e267e07?raw)