POST https://app.resemble.ai/api/v2/detect/batch

Submit up to 50 files in a single request and process them as a single logical group. The API returns a batch UUID immediately; each file is analyzed in the background, and you can poll the batch endpoint or supply a callback_url to receive results.

Batch is asynchronous only. The Prefer: wait header is not supported and returns HTTP 400 if sent.

You can submit batches in one of two ways:

• Multiple media files — attach each file as a repeated files[] field in a multipart/form-data request.
• Single zip archive — upload a .zip containing the media files; the API extracts and analyzes each entry.

Exactly one of files[] or a single file=<...>.zip must be provided per request.

Submitting multiple files

$
curl --request POST 'https://app.resemble.ai/api/v2/detect/batch' \
>
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>
  -F 'files[]=@/path/to/clip1.mp3' \
>
  -F 'files[]=@/path/to/clip2.mp4' \
>
  -F 'files[]=@/path/to/clip3.jpg' \
>
  -F 'callback_url=https://example.com/webhooks/detect-batch' \
>
  -F 'intelligence=true' \
>
  -F 'visualize=true'

Submitting a zip archive

$
curl --request POST 'https://app.resemble.ai/api/v2/detect/batch' \
>
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
>
  -F 'file=@/path/to/batch.zip' \
>
  -F 'callback_url=https://example.com/webhooks/detect-batch' \
>
  -F 'intelligence=true'

The zip is extracted server-side. Non-media entries inside the archive are skipped; subdirectories are flattened.

Batch Constraints

Requests outside these constraints are rejected with HTTP 400 before any analysis runs. If your team has insufficient wallet balance to cover the full batch, the request returns HTTP 402 with a per-file cost breakdown — no detects are created in that case (all-or-nothing).

Shared Settings

Settings supplied at the batch level are applied to every file in the batch. Per-file overrides are not currently supported.

Response

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "BATCH_UUID",
5
    "status": "processing",
6
    "total_files": 3,
7
    "completed_count": 0,
8
    "failed_count": 0,
9
    "created_at": "2024-01-15T10:30:00Z",
10
    "detect_uuids": [
11
      "DETECT_UUID_1",
12
      "DETECT_UUID_2",
13
      "DETECT_UUID_3"
14
    ]
15
  }
16
}

The response is HTTP 202 Accepted. Use the returned detect_uuids to query individual detection results via GET /detect/{uuid}, or poll the batch endpoint described below for an aggregate status.

Status values

Get Batch Status

GET https://app.resemble.ai/api/v2/detect/batch/{uuid}

Retrieve the latest aggregate status for a batch. Returns the same shape as the create response, with status, completed_count, and failed_count updated as child detects progress.

$
curl --request GET 'https://app.resemble.ai/api/v2/detect/batch/BATCH_UUID' \
>
  -H 'Authorization: Bearer YOUR_API_TOKEN'

1
{
2
  "success": true,
3
  "item": {
4
    "uuid": "BATCH_UUID",
5
    "status": "completed",
6
    "total_files": 3,
7
    "completed_count": 3,
8
    "failed_count": 0,
9
    "created_at": "2024-01-15T10:30:00Z",
10
    "detect_uuids": [
11
      "DETECT_UUID_1",
12
      "DETECT_UUID_2",
13
      "DETECT_UUID_3"
14
    ]
15
  }
16
}

If the batch UUID does not belong to your team or doesn’t exist, the API returns HTTP 404.

Callback Payload

When callback_url is provided, the API invokes it with the batch payload once the batch reaches a terminal state (completed, partially_failed, or failed). The payload mirrors the GET response shown above. To retrieve per-file results, follow up with GET /detect/{uuid} for each entry in detect_uuids.

Errors