> ## 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 Job Status

> Fetch classification results, optionally waiting for them

Check the status of a classification job. When `status` is `completed`, the `results` field contains the full classification data.

<Tip>
  **If your service can receive HTTP callbacks, you do not need this endpoint.**
  [Register a webhook](/guides/webhooks) and handle `job.completed` — results arrive
  the moment they exist and you make no status requests at all.

  Otherwise pass **`?wait=60`** below. It returns the finished job in one request
  instead of one every few seconds.
</Tip>

<ParamField path="job_id" type="string" required>
  The UUID returned by [Classify Video](/api-reference/classify-video).
</ParamField>

<ParamField query="wait" type="integer" default="0">
  Seconds to hold the request open waiting for the job to finish. `0` (the default)
  returns immediately. Maximum `90`.

  The response is returned as soon as the job reaches a terminal state, or when the
  wait elapses — whichever is first. **A timed-out wait is not an error**: you get
  the current state, exactly as `wait=0` would return, and can call again.

  Set your client's timeout above this value — a 60-second wait with a 30-second
  client timeout hangs up on a request that was about to answer.
</ParamField>

<Warning>
  Without `wait`, a 30–180 second job checked every 5 seconds costs 6–36 requests.
  On the Free tier's 10 requests/minute that can rate-limit you on a single video.
</Warning>

### Response (200 OK)

<ResponseField name="job_id" type="string">
  Job UUID.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `queued`, `downloading`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Percentage complete (0-100).
</ResponseField>

<ResponseField name="processing_tier" type="string">
  Tier used: `basic`, `enhanced`, or `premium`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of job creation.
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 timestamp of completion. `null` if not yet complete.
</ResponseField>

<ResponseField name="results" type="object">
  Classification results. `null` until `status` is `completed`.

  <Expandable title="Results fields">
    <ResponseField name="role" type="string">
      Assigned role: `Hook`, `A-Roll`, `B-Roll`, `Screen Recording`, `VO`, or `Blooper`.
    </ResponseField>

    <ResponseField name="role_confidence" type="number">
      Confidence score from 0.0 to 1.0.
    </ResponseField>

    <ResponseField name="classification_method" type="string">
      Method used: `heuristic`, `enhanced`, or `premium`.
    </ResponseField>

    <ResponseField name="semantic_label" type="string">
      Human-readable description of detected content.
    </ResponseField>

    <ResponseField name="explanation" type="string">
      Why this role was assigned.
    </ResponseField>

    <ResponseField name="suggested_filename" type="string">
      Editor-friendly filename based on content analysis.
    </ResponseField>

    <ResponseField name="suggested_folder" type="string">
      Folder path for organizing footage (e.g., `A-Roll/Interview`).
    </ResponseField>

    <ResponseField name="thumbnails" type="string[]">
      Array of keyframe thumbnail URLs (if `thumbnails` capability requested).
    </ResponseField>

    <ResponseField name="diagnostics" type="object">
      Video technical metadata (if `diagnostics` capability requested).
      Includes: `codec`, `resolution`, `fps`, `is_vfr`, `duration_seconds`, `health_score`, `container`.
    </ResponseField>

    <ResponseField name="duplicates" type="object">
      Perceptual hash data (if `duplicates` capability requested).
      Includes: `visual_fingerprint`.
    </ResponseField>

    <ResponseField name="clips" type="object[]">
      Clip candidates (if `clips` capability requested).
      Each includes: `start_time`, `end_time`, `label`, `explanation`, `confidence`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Error details if `status` is `failed`. Includes `code` and `message`.
</ResponseField>

<RequestExample>
  ```bash Wait for the result theme={null}
  curl "https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab?wait=60" \
    -H "X-API-Key: fd_live_your_key_here"
  ```

  ```bash Check without waiting theme={null}
  curl https://api.fastdrop.io/api/v1/classify/a1b2c3d4-5678-90ab-cdef-1234567890ab \
    -H "X-API-Key: fd_live_your_key_here"
  ```

  ```python Python theme={null}
  import httpx

  data = httpx.get(
      f"https://api.fastdrop.io/api/v1/classify/{job_id}",
      params={"wait": 60},
      headers={"X-API-Key": "fd_live_your_key_here"},
      timeout=75,  # must exceed `wait`
  ).json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (completed) theme={null}
  {
    "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "completed",
    "progress": 100,
    "processing_tier": "basic",
    "created_at": "2026-03-05T12:00:00Z",
    "completed_at": "2026-03-05T12:01:15Z",
    "results": {
      "role": "A-Roll",
      "role_confidence": 0.92,
      "classification_method": "heuristic",
      "semantic_label": "Interview — talking head with direct eye contact",
      "explanation": "Speaker faces camera with consistent framing and sustained speech.",
      "suggested_filename": "interview-talking-head-001.mp4",
      "suggested_folder": "A-Roll/Interview",
      "thumbnails": [
        "https://storage.fastdrop.io/thumbs/abc123-t1.jpg",
        "https://storage.fastdrop.io/thumbs/abc123-t2.jpg",
        "https://storage.fastdrop.io/thumbs/abc123-t3.jpg"
      ],
      "diagnostics": {
        "codec": "h264",
        "resolution": "1920x1080",
        "fps": 30.0,
        "is_vfr": false,
        "duration_seconds": 47.2,
        "health_score": 95,
        "container": "mp4"
      }
    }
  }
  ```

  ```json 200 (processing) theme={null}
  {
    "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "processing",
    "progress": 45,
    "processing_tier": "basic",
    "created_at": "2026-03-05T12:00:00Z",
    "completed_at": null,
    "results": null,
    "error": null
  }
  ```

  ```json 200 (failed) theme={null}
  {
    "job_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "failed",
    "progress": 0,
    "processing_tier": "basic",
    "created_at": "2026-03-05T12:00:00Z",
    "completed_at": "2026-03-05T12:00:30Z",
    "results": null,
    "error": {
      "code": "processing_failed",
      "message": "Failed to download video: 404 Not Found"
    }
  }
  ```
</ResponseExample>


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