---
title: "Submit Batch Download"
method: POST
path: "/boards/tasks/batch-download/submit"
tags: ["Board Tasks"]
---

# Submit Batch Download

`POST /boards/tasks/batch-download/submit`

Submit a batch download request for Board tasks. This is an asynchronous operation that packages selected tasks into a ZIP file. Returns a downloadTaskId for status polling.

## Headers

- `Topview-Uid` string, required
- `Authorization` string, required

## Request body

- object
  - `boardId` string, required — Board ID (required)
  - `selectAll` boolean — Whether to download all matching tasks (true) or specific tasks (false, default). When true, filter must be provided and taskIds is ignored.
  - `taskIds` string[], nullable — Task ID list to download. Required when selectAll=false. Ignored when selectAll=true.
  - `excludeTaskIds` string[], nullable — Task IDs to exclude from download. Only effective when selectAll=true. For tasks manually deselected by user.
  - `filter` object, nullable — Filter criteria for batch operation. Only effective when selectAll=true.
    - `mediaType` 'all' | 'image' | 'video' | 'audio' — Media type filter
    - `rating` 'all' | '0' | '1' | '2' | '3' | 'unrated' — Rating filter
    - `ratingOperator` '>=' | '>' | '<=' | '<' | '=' — Rating operator for range queries
    - `ratingValue` integer — Rating value for range queries
    - `toolCategory` 'image' | 'video' | 'avatar' | 'voice' | 'music' — Tool category filter
    - `toolType` string — Tool type filter (single value, for backward compatibility)
    - `toolTypes` string[] — Tool type filter (list, OR query)
    - `creatorUids` string[] — Creator UID list (OR query)
    - `groupIds` string[] — Group ID list (OR query)

## Response `200`

Batch download submitted successfully

- object
  - `code` string
  - `message` string
  - `result` object
    - `downloadTaskId` string — Unique download task ID for status polling
    - `status` 'init' | 'running' | 'success' | 'fail' — Task status (typically 'init' on submission)
    - `progress` integer — Progress percentage (0-100)
    - `processedCount` integer — Number of processed files
    - `totalCount` integer — Total number of files to process
    - `downloadUrl` string, nullable — Download URL (only when status=success)
    - `fileCount` integer, nullable — Number of files included in ZIP (only when status=success)
    - `totalSize` integer, nullable — ZIP file size in bytes (only when status=success)
    - `expiresAt` string, date-time, nullable — Download link expiration time (only when status=success)
    - `gmtCreate` string, date-time, nullable — Task creation time
    - `completedAt` string, date-time, nullable — Task completion time (only when status=success or fail)
    - `errorCode` string, nullable — Error code (only when status=fail)
    - `errorMessage` string, nullable — Error message (only when status=fail)

---

[API](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme.md) · [All operations](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topview/image-character-swap-apis-editable-in-readme/versions/83cd46ca7859/schema)