> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Batch 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 ## OpenAPI ````yaml get /v1/analytics/performance/batches/{batch_id}/diagnostics openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/analytics/performance/batches/{batch_id}/diagnostics: get: tags: - Analytics - Analytics - Performance summary: Get Batch Diagnostics description: >- 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 operationId: >- get_batch_diagnostics_v1_analytics_performance_batches__batch_id__diagnostics_get parameters: - name: batch_id in: path required: true schema: type: string title: Batch Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchDiagnostics' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: BatchDiagnostics: properties: batch_id: type: string title: Batch Id description: Batch ID batch_name: type: string title: Batch Name description: Batch name status: type: string title: Status description: Overall batch status bucket_id: type: string title: Bucket Id description: Source bucket ID current_tier: type: integer title: Current Tier description: Current tier being processed default: 0 total_tiers: type: integer title: Total Tiers description: Total number of tiers default: 1 overall_progress: type: number title: Overall Progress description: Overall progress percentage (0-100) default: 0 created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: When batch was created submitted_at: anyOf: - type: string format: date-time - type: 'null' title: Submitted At description: When batch was submitted started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When processing started completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When processing completed duration_seconds: anyOf: - type: number - type: 'null' title: Duration Seconds description: Total duration in seconds estimated_completion: anyOf: - type: string format: date-time - type: 'null' title: Estimated Completion description: Estimated completion time tiers: items: $ref: '#/components/schemas/TierDiagnostic' type: array title: Tiers description: Diagnostic info for each tier collections: items: $ref: '#/components/schemas/CollectionDiagnostic' type: array title: Collections description: Status of target collections performance_summary: anyOf: - additionalProperties: true type: object - type: 'null' title: Performance Summary description: Performance metrics summary (available after completion) insights: items: $ref: '#/components/schemas/PerformanceInsight' type: array title: Insights description: Performance insights and recommendations has_failures: type: boolean title: Has Failures description: Whether batch has any failures default: false failed_tier_count: type: integer title: Failed Tier Count description: Number of failed tiers default: 0 health: type: string title: Health description: >- 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). default: ok blocked_reason: anyOf: - type: string - type: 'null' title: Blocked Reason description: >- 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: anyOf: - type: number - type: 'null' title: Stuck Seconds description: >- How long the batch has been making no progress while PROCESSING, in seconds. None when not stuck. total_objects: type: integer title: Total Objects description: Total objects in batch default: 0 next_actions: items: type: string type: array title: Next Actions description: Recommended next steps for user type: object required: - batch_id - batch_name - status - bucket_id title: BatchDiagnostics description: |- Comprehensive batch diagnostics response. Combines batch status, task progress, collection info, and performance insights into a single response for easy frontend rendering. ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TierDiagnostic: properties: tier_num: type: integer title: Tier Num description: Tier number task_id: anyOf: - type: string - type: 'null' title: Task Id description: Task ID for this tier status: type: string title: Status description: Tier status (PENDING, PROCESSING, COMPLETED, FAILED) started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When tier started completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At description: When tier completed duration_seconds: anyOf: - type: number - type: 'null' title: Duration Seconds description: Duration in seconds progress: anyOf: - $ref: '#/components/schemas/TaskProgress' - type: 'null' description: Progress information ray_job_id: anyOf: - type: string - type: 'null' title: Ray Job Id description: Ray job ID ray_dashboard_url: anyOf: - type: string - type: 'null' title: Ray Dashboard Url description: Link to Ray dashboard error: anyOf: - type: string - type: 'null' title: Error description: Error message if failed error_type: anyOf: - type: string - type: 'null' title: Error Type description: Error type if failed requires_gpu: anyOf: - type: boolean - type: 'null' title: Requires Gpu description: >- 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: anyOf: - type: string - type: 'null' title: Ray Job Status description: >- 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. type: object required: - tier_num - status title: TierDiagnostic description: Diagnostic information for a single tier. CollectionDiagnostic: properties: collection_id: type: string title: Collection Id description: Collection ID collection_name: type: string title: Collection Name description: Collection name document_count: type: integer title: Document Count description: Number of documents in collection default: 0 expected_documents: anyOf: - type: integer - type: 'null' title: Expected Documents description: Expected document count status: type: string title: Status description: Collection status (ready, processing, empty) type: object required: - collection_id - collection_name - status title: CollectionDiagnostic description: Diagnostic information for a collection. PerformanceInsight: properties: type: type: string title: Type description: Insight type (bottleneck, optimization, warning) severity: type: string title: Severity description: Severity (info, warning, critical) message: type: string title: Message description: Human-readable message stage: anyOf: - type: string - type: 'null' title: Stage description: Related stage name metric_value: anyOf: - type: number - type: 'null' title: Metric Value description: Related metric value recommendation: anyOf: - type: string - type: 'null' title: Recommendation description: Recommended action type: object required: - type - severity - message title: PerformanceInsight description: Performance insight or recommendation. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TaskProgress: properties: processed_documents: type: integer title: Processed Documents description: Number of documents processed default: 0 total_documents: type: integer title: Total Documents description: Total documents to process default: 0 percentage: type: number title: Percentage description: Progress percentage (0-100) default: 0 type: object title: TaskProgress description: Progress information for a task. ````