---
title: "Get Batch Diagnostics"
method: GET
path: "/v1/analytics/performance/batches/{batch_id}/diagnostics"
tags: ["Analytics", "Analytics - Performance"]
---

# Get Batch Diagnostics

`GET /v1/analytics/performance/batches/{batch_id}/diagnostics`

Get comprehensive diagnostics for a batch.

Combines batch status, task progress, collection info, performance metrics,
and actionable insights into a single response for easy frontend rendering.

**Use Cases:**
- Monitor batch processing in real-time
- Debug failed batches
- View performance breakdown after completion
- Get actionable next steps

**Response includes:**
- Overall batch status and progress
- Per-tier task details with Ray job links
- Collection document counts
- Performance insights and bottlenecks (if completed)
- Error details (if failed)
- Recommended next actions

**Example:**
```bash
GET /v1/analytics/performance/batches/{batch_id}/diagnostics
```

**Perfect for:**
- Real-time progress tracking UI
- Batch monitoring dashboards
- Debugging failed extractions
- Performance optimization

## Path parameters

- `batch_id` string, required

## Response `200`

Successful Response

- BatchDiagnostics — Comprehensive batch diagnostics response. Combines batch status, task progress, collection info, and performance insights into a single response for easy frontend rendering.
  - `batch_id` string, required — Batch ID
  - `batch_name` string, required — Batch name
  - `status` string, required — Overall batch status
  - `bucket_id` string, required — Source bucket ID
  - `current_tier` integer — Current tier being processed
  - `total_tiers` integer — Total number of tiers
  - `overall_progress` number — Overall progress percentage (0-100)
  - `created_at` string, date-time, nullable — When batch was created
  - `submitted_at` string, date-time, nullable — When batch was submitted
  - `started_at` string, date-time, nullable — When processing started
  - `completed_at` string, date-time, nullable — When processing completed
  - `duration_seconds` number, nullable — Total duration in seconds
  - `estimated_completion` string, date-time, nullable — Estimated completion time
  - `tiers` TierDiagnostic[] — Diagnostic info for each tier
    - `tier_num` integer, required — Tier number
    - `task_id` string, nullable — Task ID for this tier
    - `status` string, required — Tier status (PENDING, PROCESSING, COMPLETED, FAILED)
    - `started_at` string, date-time, nullable — When tier started
    - `completed_at` string, date-time, nullable — When tier completed
    - `duration_seconds` number, nullable — Duration in seconds
    - `progress` TaskProgress — Progress information for a task.
      - `processed_documents` integer — Number of documents processed
      - `total_documents` integer — Total documents to process
      - `percentage` number — Progress percentage (0-100)
    - `ray_job_id` string, nullable — Ray job ID
    - `ray_dashboard_url` string, nullable — Link to Ray dashboard
    - `error` string, nullable — Error message if failed
    - `error_type` string, nullable — Error type if failed
    - `requires_gpu` boolean, nullable — Whether this tier's Ray job targets a GPU worker group. GPU jobs may wait minutes for a scale-from-zero node to come up plus image pull, so this widens the cold-start window before a no-progress tier is flagged stuck.
    - `ray_job_status` string, nullable — Last observed Ray job status (RUNNING, PENDING, SUCCEEDED, FAILED). PENDING means the job is queued waiting for a worker — i.e. the cluster may be provisioning rather than the job being stuck.
  - `collections` CollectionDiagnostic[] — Status of target collections
    - `collection_id` string, required — Collection ID
    - `collection_name` string, required — Collection name
    - `document_count` integer — Number of documents in collection
    - `expected_documents` integer, nullable — Expected document count
    - `status` string, required — Collection status (ready, processing, empty)
  - `performance_summary` object, nullable — Performance metrics summary (available after completion)
  - `insights` PerformanceInsight[] — Performance insights and recommendations
    - `type` string, required — Insight type (bottleneck, optimization, warning)
    - `severity` string, required — Severity (info, warning, critical)
    - `message` string, required — Human-readable message
    - `stage` string, nullable — Related stage name
    - `metric_value` number, nullable — Related metric value
    - `recommendation` string, nullable — Recommended action
  - `has_failures` boolean — Whether batch has any failures
  - `failed_tier_count` integer — Number of failed tiers
  - `health` string — Derived health signal: 'ok', 'scaling' (PROCESSING with no progress yet but still inside the GPU cold-start / cluster-provisioning window — a scale-from-zero node and image pull can take ~20 min, so this is expected, not stuck), 'stuck' (PROCESSING but no progress and the active tier's job has been PENDING past the cold-start window — its driver/worker may be unschedulable), or 'degraded' (has partial failures).
  - `blocked_reason` string, nullable — Human-readable reason the batch appears stuck/blocked, or — for health='scaling' — why it is legitimately waiting (e.g. 'cluster_cold_start: GPU workers scaling from zero'). None when health is 'ok' or 'degraded'.
  - `stuck_seconds` number, nullable — How long the batch has been making no progress while PROCESSING, in seconds. None when not stuck.
  - `total_objects` integer — Total objects in batch
  - `next_actions` string[] — Recommended next steps for user

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-08-09** `5d4c905106b4` — 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Change history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/analytics/performance/batches/:batch_id/diagnostics/get.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/e9447a01c86a/schema)