ROC Curve

Page Outline

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

---

GET/api/v1/models/{model_id}/performance/roc-curve

The Receiver Operating Characteristic (ROC) curve endpoint yields the core statistical coordinates defining a classification system's structural discriminative power. By returning the proportional trade-offs between the True Positive Rate (Sensitivity) and False Positive Rate across sliding confidence thresholds, UI dashboards can dynamically map the generalized efficacy of varying model architectures.

[!TIP] A structurally perfect model produces a roc_auc (Area Under Curve) of an exact 1.0, while a purely random un-trained discriminator rests at 0.5. If your dataset features heavy class imbalance, you should prioritize interpreting the PR Curve to obtain accurate performance perspectives.

Authentication Requirements

Access requires secure Bearer session negotiation.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: Standard model:read permissions inside the relevant organizational framework.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The core UUID representation referencing the model's environment structure.

Query Parameters

Parameter	Type	Default	Description
version_id	string	Latest Promoted	Instructs the analytics server to compute boundaries for this designated artifact.
dataset_split	string	test	Target diagnostic evaluation partition: train, validation, or test.
resolution	integer	100	Controls coordinate spacing interval boundaries (Higher resolution = smoother curve display).
class_label	string	Macro-Avg	For multi-class scenarios: compute One-vs-Rest for this specified classification tag.

Operational Behavior

The backend logic operates under strict computation rules schemas:

1. Architecture Compatibility: Will instantly return an HTTP 422 error block if invoked against a task_type: "regression" object.
2. Averaging Protocol: Should a user define a multi-class configuration without an explicit class_label, the analytics abstraction auto-computes a macro-averaged amalgamation curve structure reflecting collective performance metrics.
3. Data Downsampling: The algorithm inherently compresses raw probability threshold tracking into an equidistant array mapped to your defined resolution, reducing payload latency footprint.

Response

Responses guarantee an HTTP 200 OK header containing a precisely structured RocCurve JSON object payload.

Example JSON Response

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "roc_auc": 0.9674,
  "curve": [
    { "fpr": 0.0000, "tpr": 0.0000, "threshold": 1.0000 },
    { "fpr": 0.0120, "tpr": 0.3450, "threshold": 0.9200 },
    { "fpr": 0.0450, "tpr": 0.7830, "threshold": 0.7100 },
    { "fpr": 0.0890, "tpr": 0.9510, "threshold": 0.5000 },
    { "fpr": 1.0000, "tpr": 1.0000, "threshold": 0.0000 }
  ]
}

Error Codes

Ensure integrations capture edge-case structural rejection scenarios:

Code	Reason	Resolution
400	Bad Request	An incompatible resolution boundary was mapped.
401	Unauthorized	Unverified session token architecture in TLS layer.
404	Not Found	Requested model_id tracking structure does not align within defined organization scope.
422	Unprocessable Entity	API queried against continuous analytical regression framework.