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

# Get Batch Status

> Fetch batch status with per-video results, optionally waiting

Check the status of a batch classification job. Returns per-video results as they complete.

<Tip>
  **Prefer webhooks for batches.** Subscribe to `batch.completed` for the finished
  batch, and opt into `batch.progress` to track it as it runs — a 50-video batch is
  otherwise several minutes of silence. See [Webhooks](/guides/webhooks).
</Tip>

<ParamField path="batch_id" type="string" required>
  The `batch_id` returned by [Create Batch](/api-reference/create-batch).
</ParamField>

<ParamField query="wait" type="integer" default="0">
  Seconds to hold the request open until **every** video in the batch has finished.
  `0` (the default) returns immediately. Maximum `90`.

  A batch can outlast the maximum wait. A timed-out wait is not an error — you get
  the current state and can call again immediately. Set your client timeout above
  this value.
</ParamField>

<Warning>
  Batch status is recomputed from every job row on each request, which makes this
  the most expensive endpoint to poll blindly. A 50-video batch takes minutes;
  checking it every 3 seconds does that work hundreds of times to return the same
  answer. Use `wait`, or use webhooks.
</Warning>

### Response (200 OK)

<ResponseField name="batch_id" type="string">
  Batch identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Batch-level status:

  * `processing` — Some videos still in progress
  * `completed` — All videos finished successfully
  * `partial` — All done, but some failed
  * `failed` — All videos failed
</ResponseField>

<ResponseField name="total_videos" type="integer">
  Total number of videos in the batch.
</ResponseField>

<ResponseField name="completed_videos" type="integer">
  Number of successfully completed videos.
</ResponseField>

<ResponseField name="failed_videos" type="integer">
  Number of failed videos.
</ResponseField>

<ResponseField name="total_credits" type="integer">
  Total credits charged (pre-authorized at submission).
</ResponseField>

<ResponseField name="jobs" type="object[]">
  Per-video results. Each job includes `job_id`, `video_url`, `status`, `credits_charged`, `results` (when completed), and `error` (when failed).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.fastdrop.io/api/v1/batch/batch_xyz789 \
    -H "X-API-Key: fd_live_your_key_here"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "batch_id": "batch_xyz789",
    "status": "completed",
    "total_videos": 3,
    "completed_videos": 3,
    "failed_videos": 0,
    "total_credits": 12,
    "jobs": [
      {
        "job_id": "a1b2c3d4-...",
        "video_url": "https://example.com/video1.mp4",
        "status": "completed",
        "credits_charged": 4,
        "results": {
          "role": "A-Roll",
          "role_confidence": 0.92,
          "suggested_filename": "interview-001.mp4",
          "suggested_folder": "A-Roll/Interview"
        }
      },
      {
        "job_id": "e5f6g7h8-...",
        "video_url": "https://example.com/video2.mp4",
        "status": "completed",
        "credits_charged": 4,
        "results": {
          "role": "B-Roll",
          "role_confidence": 0.87,
          "suggested_filename": "cityscape-pan-001.mp4",
          "suggested_folder": "B-Roll/Cityscape"
        }
      },
      {
        "job_id": "i9j0k1l2-...",
        "video_url": "https://example.com/video3.mp4",
        "status": "completed",
        "credits_charged": 4,
        "results": {
          "role": "Hook",
          "role_confidence": 0.78,
          "suggested_filename": "hook-dynamic-opener-001.mp4",
          "suggested_folder": "Hook"
        }
      }
    ],
    "created_at": "2026-03-05T12:00:00Z",
    "completed_at": "2026-03-05T12:03:45Z"
  }
  ```
</ResponseExample>


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