client.models.list

A method of the Models endpoint.

list(*, model_name: str = None, training_table_name: str = None, dependent_variable: str = None, status: str = None, author: str = None, hidden: bool = None, archived: str = None, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None) → ListResponse | PaginatedResponse

List

API URL: GET /models

import civis
client = civis.APIClient()
response = client.models.list(...)

Parameters:

model_namestr, optional

If specified, will be used to filter the models returned. Substring matching is supported. (e.g., “modelName=model” will return both “model1” and “my model”).

training_table_namestr, optional

If specified, will be used to filter the models returned by the training dataset table name. Substring matching is supported. (e.g., “trainingTableName=table” will return both “table1” and “my_table”).

dependent_variablestr, optional

If specified, will be used to filter the models returned by the dependent variable column name. Substring matching is supported. (e.g., “dependentVariable=predictor” will return both “predictor” and “my predictor”).

statusstr, optional

If specified, returns models with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.

authorstr, optional

If specified, return items from any of these authors. It accepts a comma- separated list of user IDs.

hiddenbool, optional

If specified to be true, returns hidden items. Defaults to false, returning non-hidden items.

archivedstr, optional

The archival status of the items to return. One of: true, false, all. A blank value is read as ‘false’, which is also the default.

limitint, optional

Number of results to return. Defaults to its maximum of 50.

page_numint, optional

Page number of the results to return. Defaults to the first page, 1.

orderstr, optional

The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at, last_run.updated_at.

order_dirstr, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iteratorbool, optional

If True, return a generator (specifically, a civis.PaginatedResponse object) to iterate over all responses. Use it when more results than the maximum allowed by ‘limit’ are needed. When True, ‘page_num’ is ignored. If False, return a civis.ListResponse object (= a list of civis.Response objects), whose size is determined by ‘limit’. Defaults to False.

Returns:

civis.ListResponse | civis.PaginatedResponse

• idint

  The ID of the model.

• table_namestr

  The qualified name of the table containing the training set from which to build the model.

• database_idint

  The ID of the database holding the training set table used to build the model.

• credential_idint

  The ID of the credential used to read the target table. Defaults to the user’s default credential.

• model_namestr

  The name of the model.

• descriptionstr

  A description of the model.

• interaction_termsbool

  Whether to search for interaction terms.

• box_cox_transformationbool

  Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.

• model_type_idint

  The ID of the model’s type.

• primary_keystr

  The unique ID (primary key) of the training dataset.

• dependent_variablestr

  The dependent variable of the training dataset.

• dependent_variable_orderList[str]

  The order of dependent variables, especially useful for Ordinal Modeling.

• excluded_columnsList[str]

  A list of columns which will be considered ineligible to be independent variables.

• limiting_sqlstr

  A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).

• cross_validation_parameterscivis.Response

  Cross validation parameter grid for tree methods, e.g. {“n_estimators”: [100, 200, 500], “learning_rate”: [0.01, 0.1], “max_depth”: [2, 3]}.

• number_of_foldsint

  Number of folds for cross validation. Default value is 5.

• schedulecivis.Response

  • scheduledbool

    If the item is scheduled.

  • scheduled_daysList[int]

    Days of the week, based on numeric value starting at 0 for Sunday. Mutually exclusive with scheduledDaysOfMonth

  • scheduled_hoursList[int]

    Hours of the day it is scheduled on.

  • scheduled_minutesList[int]

    Minutes of the day it is scheduled on.

  • scheduled_runs_per_hourint

    Deprecated in favor of scheduled minutes.

  • scheduled_days_of_monthList[int]

    Days of the month it is scheduled on, mutually exclusive with scheduledDays.

• parent_idint

  The ID of the parent job that will trigger this model.

• time_zonestr

  The time zone of this model.

• last_runcivis.Response

  • id : int

  • statestr

    The state of the run. One of queued, running, succeeded, failed or cancelled.

  • created_atstr (time)

    The time that the run was queued.

  • started_atstr (time)

    The time that the run started.

  • finished_atstr (time)

    The time that the run completed.

  • errorstr

    The error message for this run, if present.

• usercivis.Response

  • idint

    The ID of this user.

  • namestr

    This user’s name.

  • usernamestr

    This user’s username.

  • initialsstr

    This user’s initials.

  • onlinebool

    Whether this user is online.

• created_atstr (date-time)

  The time the model was created.

• updated_atstr (date-time)

  The time the model was updated.

• current_build_statestr

  The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

• current_build_exceptionstr

  Exception message, if applicable, of the current model build.

• buildsList[civis.Response]

  A list of trained models available for making predictions.

  • idint

    The ID of the model build.

  • namestr

    The name of the model build.

  • created_atstr

    The time the model build was created.

  • descriptionstr

    A description of the model build.

  • root_mean_squared_errorfloat (float)

    A key metric for continuous models. Nil for other model types.

  • r_squared_errorfloat (float)

    A key metric for continuous models. Nil for other model types.

  • roc_aucfloat (float)

    A key metric for binary, multinomial, and ordinal models. Nil for other model types.

• predictionsList[civis.Response]

  The tables upon which the model will be applied.

  • idint

    The ID of the model to which to apply the prediction.

  • table_namestr

    The qualified name of the table on which to apply the predictive model.

  • primary_keyList[str]

    The primary key or composite keys of the table being predicted.

  • limiting_sqlstr

    A SQL WHERE clause used to scope the rows to be predicted.

  • output_tablestr

    The qualified name of the table to be created which will contain the model’s predictions.

  • statestr

    The status of the prediction. One of: “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.

• last_output_locationstr

  The output JSON for the last build.

• archivedbool

  The archival status of the requested item(s).