Explainability REST API Guide

Fetch slice query

post

Parse slice query data

Authorizations
Body
model_idstring · uuidRequired
querystringRequired
Responses
200
Successfully parsed slice query
application/json
Responseall of
post
POST /v3/slice-query/parse HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "query": "text"
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "environment_name": "text",
    "is_prod": true,
    "is_slice": true,
    "model_name": "text",
    "table_name": "text"
  }
}

Fetch slice query

post

Fetch slice query data

Authorizations
Body
model_idstring · uuidRequired
querystringRequired
samplebooleanOptional
max_rowsinteger · min: 1 · max: 10000Optional
columnsstring[]Optional
Responses
200
Slice query data fetch successful
application/json
Responseall of
post
POST /v3/slice-query/fetch HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "query": "text",
  "sample": true,
  "max_rows": 1,
  "columns": [
    "text"
  ]
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "metadata": {
      "is_slice": true,
      "columns": [
        "text"
      ],
      "dtypes": [
        "text"
      ],
      "env": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "PRE_PRODUCTION",
        "name": "text"
      },
      "model": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "version": "text"
      }
    },
    "rows": [
      []
    ]
  }
}

Get feature impact

post

Get feature impact for the given environment or a slice query

Authorizations
Body

Feature Impact api request body

data_sourceone ofRequired

Feature Impact api data sources

or
or
model_idstring · uuidRequired

Unique ID of model.

num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations. Only for non text inputs

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature. Only for non text inputs

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed. Only for non text inputs

min_supportinteger · min: 1Optional

Specify a minimum support to retrieve top words. Only for Text data (NLP models)

output_columnsstring[]Optional

Only used for NLP (TEXT inputs) models. Output column names to compute feature impact on. If None, use all.

ref_env_idstring · uuidOptional

environment to use for the reference dataset.

Responses
200
Feature Impact ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/feature-impact HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 326

{
  "data_source": {
    "source_type": "ENVIRONMENT",
    "env_id": "123e4567-e89b-12d3-a456-426614174000",
    "env_type": "PRE_PRODUCTION",
    "num_samples": 1
  },
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1,
  "min_support": 1,
  "output_columns": [
    "text"
  ],
  "ref_env_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "response_type": "FEATURE_IMPACT_TEXT",
    "model_task": "text",
    "model_input_type": "text",
    "output_name": "sentiment",
    "tokens": {},
    "min_support": 15,
    "num_inputs": 200,
    "env_name": "bank_churn",
    "env_uuid": "bcb8e333-39d1-4ba5-a485-dec1591f7122",
    "created_at": "2023-12-12 18:21:07.616438+00:00"
  }
}

Get feature importance

post

Get feature importance for the given environment or a slice query

Authorizations
Body
data_sourceone ofRequired
or
or
model_idstring · uuidRequired
num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed

ref_env_idstring · uuidOptional

environment to use for the reference dataset.

Responses
200
Feature Importance ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/feature-importance HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 284

{
  "data_source": {
    "source_type": "ENVIRONMENT",
    "env_id": "123e4567-e89b-12d3-a456-426614174000",
    "env_type": "PRE_PRODUCTION",
    "num_samples": 1
  },
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1,
  "ref_env_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "model_task": "text",
    "model_input_type": "text",
    "total_input_samples": 10000,
    "valid_input_samples": 9000,
    "ci_level": 0.9,
    "feature_names": [
      "CreditScore",
      "Geography",
      "Age"
    ],
    "fixed_sample_ci": [
      0.04,
      0.002,
      0.1
    ],
    "loss": "pointwise_logloss",
    "mean_loss": 2.41122,
    "mean_loss_ci": 0.0434,
    "mean_loss_increase_importance": [
      -0.0581,
      -0.097,
      -0.0707
    ],
    "num_refs": 500,
    "random_sample_ci": [
      0.024,
      0.0204,
      0.0246
    ],
    "num_inputs": 250,
    "num_iterations": 200,
    "env_name": "bank_churn",
    "env_uuid": "bcb8e333-39d1-4ba5-a485-dec1591f7122",
    "created_at": "2023-12-12 18:21:07.616438+00:00"
  }
}

Get model scores

post

Get model scores for the given environment or a slice query

Authorizations
Body
data_sourceone ofRequired
or
or
model_idstring · uuidRequired

Model uuid

binary_thresholdnumber · max: 1Optional

Threshold for binary classification models

top_kinteger · min: 1 · max: 500Optional

Top K for ranking models

Responses
200
Scoring ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/scores HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "data_source": {
    "source_type": "ENVIRONMENT",
    "env_id": "123e4567-e89b-12d3-a456-426614174000",
    "env_type": "PRE_PRODUCTION",
    "num_samples": 1
  },
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "binary_threshold": 1,
  "top_k": 1,
  "metrics": [
    "AUC"
  ]
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "model_task": "REGRESSION",
    "total_samples": 10000,
    "valid_samples": 9500,
    "r_squared": 0.6934094625050112,
    "root_mean_squared_error": 0.43712324037225403,
    "mean_absolute_error": 0.34032740270302,
    "predictions": [
      6.346766948699951,
      5.74676698811151
    ],
    "targets": [
      6,
      5
    ],
    "error_distribution": {
      "count": [
        2,
        6
      ],
      "bins": [
        0,
        1,
        2
      ]
    }
  }
}

Update precomputed feature impact

put

Compute and update cached feature impact on an environment

Authorizations
Body

Request body for precompute feature impact

model_idstring · uuidRequired

Unique identifier for model.

env_idstring · uuidRequired

Unique identifier for environment.

env_typestringRequired

Type of environment. Either PRE_PRODUCTION or PRODUCTION.

num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed

min_supportinteger · min: 1Optional

Used for TEXT models to specify a minimum support (number of times a specific work was present in the sample data) to retrieve top words. Default to 15.

Responses
200
Feature impact pre-computation update ran successfully on the given data
application/json
Responseall of
put
PUT /v3/analytics/precompute-feature-impact HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 178

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_type": "text",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1,
  "min_support": 1
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  }
}

Precompute feature impact

post

Compute and cache feature impact on an environment

Authorizations
Body

Request body for precompute feature impact

model_idstring · uuidRequired

Unique identifier for model.

env_idstring · uuidRequired

Unique identifier for environment.

env_typestringRequired

Type of environment. Either PRE_PRODUCTION or PRODUCTION.

num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed

min_supportinteger · min: 1Optional

Used for TEXT models to specify a minimum support (number of times a specific work was present in the sample data) to retrieve top words. Default to 15.

Responses
200
Feature impact pre-computation ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/precompute-feature-impact HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 178

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_type": "text",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1,
  "min_support": 1
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  }
}

Get precomputed feature impact

post

Get precomputed feature impact for a model

Authorizations
Body
model_idstring · uuidRequired

Unique identifier for the model.

Responses
200
Precomputed Feature impact retrieval ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/feature-impact/precomputed HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "response_type": "FEATURE_IMPACT_TEXT",
    "model_task": "text",
    "model_input_type": "text",
    "output_name": "sentiment",
    "tokens": {},
    "min_support": 15,
    "num_inputs": 200,
    "env_name": "bank_churn",
    "env_uuid": "bcb8e333-39d1-4ba5-a485-dec1591f7122",
    "created_at": "2023-12-12 18:21:07.616438+00:00"
  }
}

Update precomputed feature importance

put

Compute and update cached feature importance on an environment

Authorizations
Body
model_idstring · uuidRequired
env_idstring · uuidRequired
env_typestringRequired
num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed

Responses
200
Feature importance pre-computation update ran successfully on the given data
application/json
Responseall of
put
PUT /v3/analytics/precompute-feature-importance HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 162

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_type": "text",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  }
}

Precompute feature importance

post

Compute and cache feature importance on an environment

Authorizations
Body
model_idstring · uuidRequired
env_idstring · uuidRequired
env_typestringRequired
num_refsinteger · min: 1 · max: 1000000Optional

Number of reference points used in the explanations

num_iterationsinteger · min: 1 · max: 100000Optional

The maximum number of ablated model inferences per feature

ci_levelnumber · max: 1Optional

The confidence interval level (between 0 and 1) to use for all confidence intervals computed

Responses
200
Feature importance pre-computation ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/precompute-feature-importance HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 162

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_id": "123e4567-e89b-12d3-a456-426614174000",
  "env_type": "text",
  "num_refs": 1,
  "num_iterations": 1,
  "ci_level": 1
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "job": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  }
}

Get precomputed feature importance

post

Get precomputed feature importance for a model

Authorizations
Body
model_idstring · uuidRequired

Unique identifier for model.

Responses
200
Precomputed Feature importance retrieval ran successfully on the given data
application/json
Responseall of
post
POST /v3/analytics/feature-importance/precomputed HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "model_task": "text",
    "model_input_type": "text",
    "total_input_samples": 10000,
    "valid_input_samples": 9000,
    "ci_level": 0.9,
    "feature_names": [
      "CreditScore",
      "Geography",
      "Age"
    ],
    "fixed_sample_ci": [
      0.04,
      0.002,
      0.1
    ],
    "loss": "pointwise_logloss",
    "mean_loss": 2.41122,
    "mean_loss_ci": 0.0434,
    "mean_loss_increase_importance": [
      -0.0581,
      -0.097,
      -0.0707
    ],
    "num_refs": 500,
    "random_sample_ci": [
      0.024,
      0.0204,
      0.0246
    ],
    "num_inputs": 250,
    "num_iterations": 200,
    "env_name": "bank_churn",
    "env_uuid": "bcb8e333-39d1-4ba5-a485-dec1591f7122",
    "created_at": "2023-12-12 18:21:07.616438+00:00"
  }
}
post

Get predictions from a model

Authorizations
Body
model_idstring · uuidRequired
chunk_sizeintegerOptional
dataobject[]RequiredExample: {"CreditScore":619,"Geography":"France","Gender":"Female","Age":42,"Tenure":2,"Balance":0,"NumOfProducts":1,"HasCrCard":"Yes","IsActiveMember":"Yes","EstimatedSalary":101348.88}
Responses
200
Predictions ran successfully on the given data
application/json
Responseall of
post
POST /v3/predict HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 253

{
  "model_id": "123e4567-e89b-12d3-a456-426614174000",
  "chunk_size": 1,
  "data": [
    {
      "CreditScore": 619,
      "Geography": "France",
      "Gender": "Female",
      "Age": 42,
      "Tenure": 2,
      "Balance": 0,
      "NumOfProducts": 1,
      "HasCrCard": "Yes",
      "IsActiveMember": "Yes",
      "EstimatedSalary": 101348.88
    }
  ]
}
{
  "api_version": "3.0",
  "kind": "NORMAL",
  "data": {
    "predictions": [
      {
        "probability_christian": 0.706
      }
    ]
  }
}

Last updated

Was this helpful?