Explain Model Aggregate

Explain a prediction cohort/contrast or return model-level descriptions.

POST /models/{model_id}/explain/aggregate

Explain Model Aggregate

cURL

curl --request POST \
  --url https://api.woodwide.ai/models/{model_id}/explain/aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_version_id": "<string>",
  "row_ids": [
    123
  ],
  "reference_row_ids": [
    123
  ],
  "focal_group_label": "<string>",
  "reference_group_label": "<string>",
  "target_class": "<string>",
  "refresh": false
}
'

202

{
  "id": "<string>",
  "type": "<string>",
  "status": "initializing",
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "created_by": {},
  "actor_name": "<string>",
  "model_type": "<string>",
  "model_id": "<string>",
  "dataset_id": "<string>",
  "dataset_name": "<string>",
  "input_filename": "<string>",
  "parent_job_id": "<string>",
  "input": {},
  "output": {},
  "resources": {
    "dataset": {
      "id": "<string>",
      "version_id": "<string>",
      "version_number": 123,
      "archived": false
    },
    "type": "dataset_ingest"
  },
  "explanations": [
    {
      "id": "<string>",
      "explanation_text": "<string>",
      "explanation_label": "<string>",
      "explanation_gloss": "<string>",
      "feature_contributions": [
        {}
      ],
      "prediction_flip": {}
    }
  ],
  "error_message": "<string>",
  "woodwide_runtime_version": "<string>",
  "credits_consumed": 123,
  "progress": 123,
  "current_step": 123,
  "total_steps": 123,
  "current_phase": "ssl",
  "metrics_history": [
    {
      "step": 123,
      "train_loss": 123,
      "val_loss": 123
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

model_id · string · required

Body

application/json

Explain a prediction cohort, contrast, or persisted model-level description.

model_version_id · string | null

Public model-version ID. Omit to pin the latest ready version.

row_ids · (integer | string)[] | null

Focal cohort IDs. Null requests model-level descriptions.

reference_row_ids · (integer | string)[] | null

Optional explicit comparison cohort; omitted means all other rows.

focal_group_label · string | null

Optional plain-language name for the focal cohort in the gloss.

Required string length: 1 - 128

Pattern: ^[^\r\n]+$

reference_group_label · string | null

Optional plain-language name for an explicit comparison cohort.

Required string length: 1 - 128

Pattern: ^[^\r\n]+$

target_class · string | null

Exact classification label. Binary models default to the positive class.

Minimum string length: 1

refresh · boolean · default: false

Recompute model-level descriptions instead of using persisted ones.

Response

202

application/json

Successful Response

Detailed job information.

Extends Job with input/output payloads, typed resource references, error details, and billing information.

id · string · required

Public ID of the job (e.g. job_A8K2P9QX).

type · string · required

Job type: dataset_ingest, train, infer_sync, or infer_batch.

status · enum<string> · required

Job status: initializing, pending, queued, running, succeeded, failed, canceled, or rejected. For dataset_ingest jobs, may also be 'waiting_for_upload'.

Available options: initializing, pending, queued, running, succeeded, failed, canceled, rejected, waiting_for_upload

created_at · string<date-time> · required

started_at · string<date-time> | null

finished_at · string<date-time> | null

created_by · Created By · object | null

Who created this job: {principal_type, user_id, api_key_id}.

actor_name · string | null

Display name of who created the job: the user's display name (email fallback), or the API key's name for API-key principals. Populated on dashboard-activity rows; null when the creator is unknown.

model_type · string | null

Model task type when applicable (e.g. prediction, clustering, anomaly). Derived from job input or the linked model; null for jobs without a model context.

model_id · string | null

Public ID of the parent model when the job is tied to a model (training, inference); null otherwise.

dataset_id · string | null

Public ID of the dataset when the job references a dataset version (e.g. batch inference on curated data); null for file-only inference and other jobs.

dataset_name · string | null

Display name of the linked dataset when resolved via dataset_version; null when there is no dataset or the name is unavailable.

input_filename · string | null

Original name of the uploaded file for file-backed jobs (sync/async file inference); null when the job referenced a dataset or carries no uploaded file.

parent_job_id · string | null

Public ID of the parent job when this job consumes outputs from it as part of a compound inference/training chain.

input · Input · object | null

output · Output · object | null

resources · IngestResources · object

Resources for a dataset_ingest job.

IngestResources

TrainResources

InferSyncResources

InferBatchResources

ModelExplainResources

Show child attributes

explanations · JobExplanationRow · object[] | null

Inline row explanations for succeeded infer_explain jobs.

Show child attributes

error_message · string | null

Human-readable error message if the job failed.

woodwide_runtime_version · string | null

ML runtime version used for this job.

credits_consumed · number | null

Credits consumed by this job (null if not yet finalized).

progress · number | null

Progress percentage (0-100). For training jobs, tracks training progress.

current_step · integer | null

Current training step (training jobs only). Counts SSL + finetune steps.

total_steps · integer | null

Total training steps planned for this job (training jobs only).

current_phase · enum<string> | null

Current training phase: ssl (self-supervised pre-training) or finetune (supervised head finetune). Training jobs only; null for unsupervised model types that have no training loop.

Available options: ssl, finetune

metrics_history · MetricPoint · object[] | null

Bounded series of per-interval training metrics (capped at 200 points, downsampled in place). Training jobs only; null for unsupervised paths and for jobs before the first validation gate.

Show child attributes