Precision-Recall Curve

Page Outline

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

---

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

The Precision-Recall (PR) Curve API exports the mathematical telemetry required to graph how a classification model balances false positives (Precision) against false negatives (Recall) across a sweeping spectrum of probability thresholds.

[!TIP] While ROC curves are ubiquitous, PR curves are the undisputed gold standard for judging predictive accuracy on heavily unbalanced datasets—such as fraud detection flows where the positive class represents less than 1% of the data. Use the average_precision index as your primary optimization guide in these scenarios.

Authentication Requirements

Accessing diagnostic graphing data requires verified session authenticity.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: Role-Based Access Control demands minimum model:read permissions attached to the organizational group.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The core UUID string defining the specific classification architecture.

Query Parameters

Parameter	Type	Default	Description
version_id	string	Latest Promoted	Specifies historical evaluation constraints. Promoted target utilized if undefined.
dataset_split	string	test	Dictates source evaluation scoring logic: train, validation, or test.
resolution	integer	100	Defines the threshold granularity limits. Higher resolution = smoother graph rendering (hard cap: 500).
class_label	string	None	Mandatory for multi-class architectures. Isolates graphing data mathematically against a One-vs-Rest calculation schema.

Operational Behavior

When streaming coordinate structures:

1. Architecture Paradigm: Solely compatible with binary and multi-class probabilistic engines (task_type: "classification").
2. Average Precision Baseline: The average_precision metric dynamically applies a step-interpolated integration strategy tracking strictly to standard scientific computing paradigms (e.g., scikit-learn).
3. Data Downsampling: The backend actively compresses the curve matrix length to perfectly match the resolution integer, guaranteeing constant UI rendering speeds regardless of dataset volume.

Response

The transaction finalizes via an HTTP 200 OK header carrying a structured PrCurve JSON payload.

Example JSON Response

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "average_precision": 0.9412,
  "curve": [
    { "precision": 1.0000, "recall": 0.0000, "threshold": 1.0000 },
    { "precision": 0.9714, "recall": 0.4550, "threshold": 0.8000 },
    { "precision": 0.9320, "recall": 0.7812, "threshold": 0.6000 },
    { "precision": 0.8755, "recall": 0.9430, "threshold": 0.4000 },
    { "precision": 0.7200, "recall": 1.0000, "threshold": 0.0000 }
  ]
}

Error Codes

Implement exception trapping for the standard failures:

Code	Reason	Resolution
400	Bad Request	You omitted class_label for a multi-class model architecture.
401	Unauthorized	Unverified JWT syntax.
404	Not Found	Asset metadata failure involving the requested model_id.
422	Unprocessable Entity	API queried against a linear or logistic regression module.