Misclassification Errors

Page Outline

• Authentication Requirements
• Path Parameters
• Query Parameters
• Operational Behavior
• Response
  • Example JSON Response
• Error Codes

---

GET/api/v1/models/{model_id}/performance/misclassification-errors

The Misclassification Errors API provides a surgical tool for root-cause analysis of model underperformance. While aggregate benchmarks tell you that a model failed, this endpoint tells you why — returning heavily scrutinized samples of individual data records where the model's predicted inference blatantly diverged from the established ground-truth label.

[!TIP] Combine the predicted_label and true_label filters to isolate specific edge-case cross-talk (e.g., exclusively viewing instances where the model incorrectly flagged a neutral transaction as fraud). Highly confident errors often expose corrupted training data ingestion pipelines or critical missing feature sets.

Authentication Requirements

This endpoint returns raw underlying feature data belonging to the dataset and is strictly authorized.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: An elevated minimum dataset:read AND model:read permission policy must trace back to the user context.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The core UUID (mdl-xxx) referencing the model architecture to profile for errors.

Query Parameters

Leverage these parameters to perform highly targeted behavioral queries on error classes.

Parameter	Type	Default	Description
version_id	string	Latest Promoted	Specifies the training loop version parameter.
dataset_split	string	test	Target diagnostic evaluation partition: train, validation, or test.
limit	integer	50	Output constraint boundary. Maximum pagination threshold hard-capped at 500.
true_label	string	None	Constrains results strictly to samples where actual truth equals this explicit string.
predicted_label	string	None	Constrains results to records the classifier falsely assigned this specific classification.
min_confidence	float	None	Bounded threshold (0.0 to 1.0). Discards any error records where the softmax probability was below this value, zeroing in on high-confidence hallucination.

Operational Behavior

1. Scope Validation: Only classification tasks support diagnostic record dumps. Regression analytics rely on residual plotting methodologies (see Feature Importance). Returns HTTP 422 Unprocessable Entity if malformed.
2. Sampling Algorithm: Due to vast potential error volumes, matched records are stochastically sampled out of the target pool, meaning subsequent calls may yield slightly rotated output distributions.
3. Feature Sanitization: The extracted features block is aggressively sanitized, omitting extraneous metadata mapped outside the model's stated config footprint.

Response

The backend renders a MisclassificationErrors object inside an HTTP 200 OK transaction frame.

Example JSON Response

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "total_misclassified": 650,
  "returned": 2,
  "records": [
    {
      "row_id": "rec-10042-uuid",
      "features": { 
        "age_bracket": 34, 
        "tenure": 2, 
        "monthly_spend": 89.99, 
        "support_tickets_ltd": 0 
      },
      "true_label": "churned",
      "predicted_label": "not_churned",
      "confidence": 0.8755
    },
    {
      "row_id": "rec-20817-uuid",
      "features": { 
        "age_bracket": 52, 
        "tenure": 10, 
        "monthly_spend": 210.00, 
        "support_tickets_ltd": 1 
      },
      "true_label": "not_churned",
      "predicted_label": "churned",
      "confidence": 0.9120
    }
  ]
}

Error Codes

Safeguard integrations by capturing standard fault mechanisms:

Code	Reason	Resolution
400	Bad Request	The integer boundary for limit breached maximum configurations.
401	Unauthorized	Unverified session token architecture.
404	Not Found	Requested model_id context scope untraceable inside the organizational bounds.
422	Unprocessable Entity	Target engine defined as numerical continuous regression entity.