API Resources¶
Credentials¶
-
class
Credentials(session, return_type='civis')¶ Methods
get(id)Get a credential list(**kwargs)List credentials post(type, username, password, **kwargs)Create or update a credential post_authenticate(url, remote_host_type, ...)Authenticate against a remote host post_temporary(id, **kwargs)Generate a temporary credential for accessing S3 put(id, type, username, password, **kwargs)Update an existing credential -
get(id)¶ Get a credential
Parameters: id : integer
The ID of the credential.
Returns: id : integer
The ID of the credential.
name : string
The name identifying the credential
type : string
The credential’s type.
username : string
The username for the credential.
description : string
A long description of the credential.
owner : string
The name of the user who this credential belongs to.
remote_host_id : integer
The ID of the remote host associated with this credential.
remote_host_name : string
The name of the remote host associated with this credential.
created_at : string/time
The creation time for this credential.
updated_at : string/time
The last modification time for this credential.
-
list(**kwargs)¶ List credentials
Parameters: type : string, optional
The type (or types) of credentials to return. One or more of: Amazon Web Services S3, BSD::API, CASS/NCOA PAF, Catalist::API, Catalist::SFTP, Certificate, Civis Platform, Custom, Database, Google, Github, JobTraits::Ftp, Salesforce User, Salesforce Client, Silverpop Application, Silverpop Refresh Token, Silverpop User, TableauUser, VAN::MyVoterFile, VAN::MyCampaign, and VAN::BothModes. Specify multiple values as a comma- separated list (e.g., “A,B”).
default : boolean, optional
If true, will return a list with a single credential which is the current user’s default credential.
limit : integer, optional
Number of results to return. Defaults to its maximum of 1000.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, created_at, name.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the credential.
name : string
The name identifying the credential
type : string
The credential’s type.
username : string
The username for the credential.
description : string
A long description of the credential.
owner : string
The name of the user who this credential belongs to.
remote_host_id : integer
The ID of the remote host associated with this credential.
remote_host_name : string
The name of the remote host associated with this credential.
created_at : string/time
The creation time for this credential.
updated_at : string/time
The last modification time for this credential.
-
post(type, username, password, **kwargs)¶ Create or update a credential
Parameters: type : string
username : string
The username for the credential.
password : string
The password for the credential.
name : string, optional
The name identifying the credential.
description : string, optional
A long description of the credential.
remote_host_id : integer, optional
The ID of the remote host associated with the credential.
remote_host : dict, optional:
- name : string The human readable name for the remote host. - url : string The URL to your host. - type : string The type of remote host. One of: RemoteHostTypes::BSD, RemoteHostTypes::Ftp, RemoteHostTypes::Github, RemoteHostTypes::GoogleDoc, RemoteHostTypes::JDBC, RemoteHostTypes::Redshift, RemoteHostTypes::Salesforce, and RemoteHostTypes::Van
Returns: id : integer
The ID of the credential.
name : string
The name identifying the credential
type : string
The credential’s type.
username : string
The username for the credential.
description : string
A long description of the credential.
owner : string
The name of the user who this credential belongs to.
remote_host_id : integer
The ID of the remote host associated with this credential.
remote_host_name : string
The name of the remote host associated with this credential.
created_at : string/time
The creation time for this credential.
updated_at : string/time
The last modification time for this credential.
-
post_authenticate(url, remote_host_type, username, password)¶ Authenticate against a remote host
Parameters: url : string
The URL to your host.
remote_host_type : string
The type of remote host. One of: RemoteHostTypes::BSD, RemoteHostTypes::Ftp, RemoteHostTypes::Github, RemoteHostTypes::GoogleDoc, RemoteHostTypes::JDBC, RemoteHostTypes::Redshift, RemoteHostTypes::Salesforce, and RemoteHostTypes::Van
username : string
The username for the credential.
password : string
The password for the credential.
Returns: id : integer
The ID of the credential.
name : string
The name identifying the credential
type : string
The credential’s type.
username : string
The username for the credential.
description : string
A long description of the credential.
owner : string
The name of the user who this credential belongs to.
remote_host_id : integer
The ID of the remote host associated with this credential.
remote_host_name : string
The name of the remote host associated with this credential.
created_at : string/time
The creation time for this credential.
updated_at : string/time
The last modification time for this credential.
-
post_temporary(id, **kwargs)¶ Generate a temporary credential for accessing S3
Parameters: id : integer
The ID of the credential.
duration : integer, optional
The number of seconds the temporary credential should be valid. Defaults to 15 minutes. Must not be less than 15 minutes or greater than 36 hours.
Returns: access_key : string
The identifier of the credential.
secret_access_key : string
The secret part of the credential.
session_token : string
The session token identifier.
-
put(id, type, username, password, **kwargs)¶ Update an existing credential
Parameters: id : integer
The ID of the credential.
type : string
username : string
The username for the credential.
password : string
The password for the credential.
name : string, optional
The name identifying the credential.
description : string, optional
A long description of the credential.
remote_host_id : integer, optional
The ID of the remote host associated with the credential.
remote_host : dict, optional:
- name : string The human readable name for the remote host. - url : string The URL to your host. - type : string The type of remote host. One of: RemoteHostTypes::BSD, RemoteHostTypes::Ftp, RemoteHostTypes::Github, RemoteHostTypes::GoogleDoc, RemoteHostTypes::JDBC, RemoteHostTypes::Redshift, RemoteHostTypes::Salesforce, and RemoteHostTypes::Van
Returns: id : integer
The ID of the credential.
name : string
The name identifying the credential
type : string
The credential’s type.
username : string
The username for the credential.
description : string
A long description of the credential.
owner : string
The name of the user who this credential belongs to.
remote_host_id : integer
The ID of the remote host associated with this credential.
remote_host_name : string
The name of the remote host associated with this credential.
created_at : string/time
The creation time for this credential.
updated_at : string/time
The last modification time for this credential.
-
Databases¶
-
class
Databases(session, return_type='civis')¶ Methods
delete_whitelist_ips(id, whitelisted_ip_id)Remove a whitelisted IP address get_whitelist_ips(id, whitelisted_ip_id)View details about a whitelisted IP list()List databases list_schemas(id)List schemas in this database list_whitelist_ips(id)List whitelisted IPs for the specified database post_whitelist_ips(id, subnet_mask)Whitelist an IP address -
delete_whitelist_ips(id, whitelisted_ip_id)¶ Remove a whitelisted IP address
Parameters: id : integer
The ID of the database this rule is applied to.
whitelisted_ip_id : integer
The ID of this whitelisted IP address.
Returns: None
Response code 204: success
-
get_whitelist_ips(id, whitelisted_ip_id)¶ View details about a whitelisted IP
Parameters: id : integer
The ID of the database this rule is applied to.
whitelisted_ip_id : integer
The ID of this whitelisted IP address.
Returns: id : integer
The ID of this whitelisted IP address.
remote_host_id : integer
The ID of the database this rule is applied to.
security_group_id : string
The ID of the security group this rule is applied to.
subnet_mask : string
The subnet mask that is allowed by this rule.
authorized_by : string
The user who authorized this rule.
is_active : boolean
True if the rule is applied, false if it has been revoked.
created_at : string/time
The time this rule was created.
updated_at : string/time
The time this rule was last updated.
-
list()¶ List databases
Returns: id : integer
The ID for the database.
name : string
The name of the database.
-
list_schemas(id)¶ List schemas in this database
Parameters: id : integer
The ID of the database.
Returns: schema : string
The name of a schema.
-
list_whitelist_ips(id)¶ List whitelisted IPs for the specified database
Parameters: id : integer
The ID for the database.
Returns: id : integer
The ID of this whitelisted IP address.
remote_host_id : integer
The ID of the database this rule is applied to.
security_group_id : string
The ID of the security group this rule is applied to.
subnet_mask : string
The subnet mask that is allowed by this rule.
created_at : string/time
The time this rule was created.
updated_at : string/time
The time this rule was last updated.
-
post_whitelist_ips(id, subnet_mask)¶ Whitelist an IP address
Parameters: id : integer
The ID of the database this rule is applied to.
subnet_mask : string
The subnet mask that is allowed by this rule.
Returns: id : integer
The ID of this whitelisted IP address.
remote_host_id : integer
The ID of the database this rule is applied to.
security_group_id : string
The ID of the security group this rule is applied to.
subnet_mask : string
The subnet mask that is allowed by this rule.
authorized_by : string
The user who authorized this rule.
is_active : boolean
True if the rule is applied, false if it has been revoked.
created_at : string/time
The time this rule was created.
updated_at : string/time
The time this rule was last updated.
-
Files¶
-
class
Files(session, return_type='civis')¶ Methods
delete_projects(id, project_id)Remove a Data::S3File from a project delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object get(id)Get details about a file list_projects(id)List the projects a Data::S3File belongs to list_shares(id)List users and groups permissioned on this object post(name, **kwargs)Initiate an upload of a file into the platform put_projects(id, project_id)Add a Data::S3File to a project put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object -
delete_projects(id, project_id)¶ Remove a Data::S3File from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(id)¶ Get details about a file
Parameters: id : integer
The ID of the file object.
Returns: id : integer
The ID of the file object.
name : string
The file name.
created_at : string/date-time
The date and time the file was created.
file_size : integer
The file size.
expires_at : string/date-time
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
download_url : string
A JSON string containing information about the URL of the file.
file_url : string
The URL that may be used to download the file.
-
list_projects(id)¶ List the projects a Data::S3File belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
post(name, **kwargs)¶ Initiate an upload of a file into the platform
Parameters: name : string
The file name.
expires_at : string/date-time, optional
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
Returns: id : integer
The ID of the file object.
name : string
The file name.
created_at : string/date-time
The date and time the file was created.
file_size : integer
The file size.
expires_at : string/date-time
The date and time the file will expire. If not specified, the file will expire in 30 days. To keep a file indefinitely, specify null.
upload_url : string
The URL that may be used to upload a file. To use the upload URL, initiate a POST request to the given URL with the file you wish to import as the “file” form field.
upload_fields : dict
A hash containing the form fields to be included with the POST request.
-
put_projects(id, project_id)¶ Add a Data::S3File to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
Imports¶
-
class
Imports(session, return_type='civis')¶ Methods
delete_files_runs(id, run_id)Cancel a run delete_projects(id, project_id)Remove a JobTypes::Import from a project delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object delete_syncs(id, sync_id)Delete a sync get(id)Get details about an import get_batches(id)Get details about a batch import get_files_runs(id, run_id)Check status of a run list(**kwargs)List imports list_batches(**kwargs)List batch imports list_files_runs(id, **kwargs)List runs for the given import list_projects(id)List the projects a JobTypes::Import belongs to list_runs(id)Get the run history of this import list_shares(id)List users and groups permissioned on this object post(name, sync_type, is_outbound, **kwargs)Create a new import configuration post_batches(file_ids, schema, table, ...)Upload multiple files to Redshift post_cancel(id)Cancel a run post_files(schema, name, remote_host_id, ...)Initate an import of a tabular file into the platform post_files_runs(id)Start a run post_runs(id)Run an import post_syncs(id, source, destination, **kwargs)Create a sync put(id, name, sync_type, is_outbound, **kwargs)Update an import put_archive(id, status)Update the archive status of this object put_projects(id, project_id)Add a JobTypes::Import to a project put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object put_syncs(id, sync_id, source, destination, ...)Update a sync -
delete_files_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the import.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
-
delete_projects(id, project_id)¶ Remove a JobTypes::Import from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_syncs(id, sync_id)¶ Delete a sync
Parameters: id : integer
The ID of the import to fetch.
sync_id : integer
The ID of the sync to fetch.
Returns: None
Response code 204: success
-
get(id)¶ Get details about an import
Parameters: id : integer
The ID for the import.
Returns: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
source : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
destination : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer
Parent id to trigger this import from
id : integer
The ID for the import.
is_outbound : boolean
syncs : list:
List of syncs. - id : integer - source : dict:: - id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename. - destination : dict:: - path : string The schema.tablename to sync to. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
state : string
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this import.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
get_batches(id)¶ Get details about a batch import
Parameters: id : integer
The ID for the import.
Returns: id : integer
The ID for the import.
schema : string
The destination schema name. This schema must already exist in Redshift.
table : string
The destination table name, without the schema prefix. This table must already exist in Redshift.
remote_host_id : integer
The ID of the destination database host.
state : string
The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error returned by the run, if any.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
-
get_files_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the import.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
import_id : integer
The ID of the import.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list(**kwargs)¶ List imports
Parameters: type : string, optional
If specified, return imports of these types. It accepts a comma-separated list, possible values are ‘AutoImport’, ‘DbSync’, ‘Salesforce’, ‘GdocImport’.
author : string, optional
If specified, return imports from this author. It accepts a comma-separated list of author ids.
destination : string, optional
If specified, returns imports with one of these destinations. It accepts a comma-separated list of remote host ids.
status : string, optional
If specified, returns imports with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, 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_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
source : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
destination : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
id : integer
The ID for the import.
is_outbound : boolean
state : string
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
time_zone : string
The time zone of this import.
archived : string
The archival status of the requested object(s).
-
list_batches(**kwargs)¶ List batch imports
Parameters: limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, created_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID for the import.
schema : string
The destination schema name. This schema must already exist in Redshift.
table : string
The destination table name, without the schema prefix. This table must already exist in Redshift.
remote_host_id : integer
The ID of the destination database host.
state : string
The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error returned by the run, if any.
-
list_files_runs(id, **kwargs)¶ List runs for the given import
Parameters: id : integer
The ID of the import.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the run.
import_id : integer
The ID of the import.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list_projects(id)¶ List the projects a JobTypes::Import belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
-
list_runs(id)¶ Get the run history of this import
Parameters: id : integer
Returns: id : integer
state : string
created_at : string/time
The time that the run was queued.
started_at : string/time
The time that the run started.
finished_at : string/time
The time that the run completed.
error : string
The error message for this run, if present.
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
post(name, sync_type, is_outbound, **kwargs)¶ Create a new import configuration
Parameters: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
is_outbound : boolean
source : dict, optional:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id.
destination : dict, optional:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict, optional:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer, optional
Parent id to trigger this import from
next_run_at : string/time, optional
The time of the next scheduled run.
time_zone : string, optional
The time zone of this import.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
source : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
destination : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer
Parent id to trigger this import from
id : integer
The ID for the import.
is_outbound : boolean
syncs : list:
List of syncs. - id : integer - source : dict:: - id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename. - destination : dict:: - path : string The schema.tablename to sync to. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
state : string
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this import.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
post_batches(file_ids, schema, table, remote_host_id, credential_id, **kwargs)¶ Upload multiple files to Redshift
Parameters: file_ids : list
The file IDs for the import.
schema : string
The destination schema name. This schema must already exist in Redshift.
table : string
The destination table name, without the schema prefix. This table must already exist in Redshift.
remote_host_id : integer
The ID of the destination database host.
credential_id : integer
The ID of the credentials to be used when performing the database import.
column_delimiter : string, optional
The column delimiter for the file. Valid arguments are “comma”, “tab”, and “pipe”. If unspecified, defaults to “comma”.
first_row_is_header : boolean, optional
A boolean value indicating whether or not the first row is a header row. If unspecified, defaults to false.
compression : string, optional
The type of compression. Valid arguments are “gzip”, “zip”, and “none”. If unspecified, defaults to “gzip”.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: id : integer
The ID for the import.
schema : string
The destination schema name. This schema must already exist in Redshift.
table : string
The destination table name, without the schema prefix. This table must already exist in Redshift.
remote_host_id : integer
The ID of the destination database host.
state : string
The state of the run; one of “queued”, “running”, “succeeded”, “failed”, or “cancelled”.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error returned by the run, if any.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
-
post_cancel(id)¶ Cancel a run
Parameters: id : integer
The ID of the job.
Returns: id : integer
The ID of the run.
state : string
The state of the run, one of ‘queued’, ‘running’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
-
post_files(schema, name, remote_host_id, credential_id, **kwargs)¶ Initate an import of a tabular file into the platform
Parameters: schema : string
The schema of the destination table.
name : string
The name of the destination table.
remote_host_id : integer
The id of the destination database host.
credential_id : integer
The id of the credentials to be used when performing the database import.
max_errors : integer, optional
The maximum number of rows with errors to remove from the import before failing.
existing_table_rows : string, optional
The behaviour if a table with the requested name already exists. One of “fail”, “truncate”, “append”, or “drop”.Defaults to “fail”.
distkey : string, optional
The column to use as the distkey for the table.
sortkey1 : string, optional
The column to use as the sort key for the table.
sortkey2 : string, optional
The second column in a compound sortkey for the table.
column_delimiter : string, optional
The column delimiter of the file. If column_delimiter is null or omitted, it will be auto-detected. Valid arguments are “comma”, “tab”, and “pipe”.
first_row_is_header : boolean, optional
A boolean value indicating whether or not the first row is a header row. If first_row_is_header is null or omitted, it will be auto-detected.
multipart : boolean, optional
If true, the upload URI will require a multipart/form-data POST request. Defaults to false.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: id : integer
The id of the import.
upload_uri : string
The URI which may be used to upload a tabular file for import. You must use this URI to upload the file you wish imported and then inform the Civis API when your upload is complete using the URI given by the runUri field of this reponse.
run_uri : string
The URI to POST to once the file upload is complete. After uploading the file using the URI given in the uploadUri attribute of the reponse, POST to this URI to initiate the import of your uploaded file into the platform.
upload_fields : dict
If multipart was set to true, these fields should be included in the multipart upload.
-
post_files_runs(id)¶ Start a run
Parameters: id : integer
The ID of the import.
Returns: id : integer
The ID of the run.
import_id : integer
The ID of the import.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
post_runs(id)¶ Run an import
Parameters: id : integer
The ID of the import to run.
Returns: run_id : integer
The ID of the new run triggered.
-
post_syncs(id, source, destination, **kwargs)¶ Create a sync
Parameters: id : integer
source : dict:
- path : string The path of the dataset to sync from; for a database source, schema.tablename.
destination : dict:
- path : string The schema.tablename to sync to.
advanced_options : dict, optional:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
Returns: id : integer
source : dict:
- id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename.
destination : dict:
- path : string The schema.tablename to sync to.
advanced_options : dict:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
-
put(id, name, sync_type, is_outbound, **kwargs)¶ Update an import
Parameters: id : integer
The ID for the import.
name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
is_outbound : boolean
source : dict, optional:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id.
destination : dict, optional:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict, optional:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer, optional
Parent id to trigger this import from
next_run_at : string/time, optional
The time of the next scheduled run.
time_zone : string, optional
The time zone of this import.
Returns: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
source : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
destination : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer
Parent id to trigger this import from
id : integer
The ID for the import.
is_outbound : boolean
syncs : list:
List of syncs. - id : integer - source : dict:: - id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename. - destination : dict:: - path : string The schema.tablename to sync to. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
state : string
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this import.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
put_archive(id, status)¶ Update the archive status of this object
Parameters: id : integer
The ID of the object.
status : boolean
The desired archived status of the object.
Returns: name : string
The name of the import.
sync_type : string
The type of sync to perform; one of Dbsync, AutoImport, SilverpopDataImport, SilverpopContactImport, GdocImport, GdocExport, and Salesforce.
source : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
destination : dict:
- remote_host_id : integer - credential_id : integer - additional_credentials : list Array that holds additional credentials used for specific imports. For salesforce imports, the first and only element is the client credential id. - name : string
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
parent_id : integer
Parent id to trigger this import from
id : integer
The ID for the import.
is_outbound : boolean
syncs : list:
List of syncs. - id : integer - source : dict:: - id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename. - destination : dict:: - path : string The schema.tablename to sync to. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
state : string
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this import.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
put_projects(id, project_id)¶ Add a JobTypes::Import to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
put_syncs(id, sync_id, source, destination, **kwargs)¶ Update a sync
Parameters: id : integer
The ID of the import to fetch.
sync_id : integer
The ID of the sync to fetch.
source : dict:
- path : string The path of the dataset to sync from; for a database source, schema.tablename.
destination : dict:
- path : string The schema.tablename to sync to.
advanced_options : dict, optional:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
Returns: id : integer
source : dict:
- id : integer The ID of the table or file, if available. - path : string The path of the dataset to sync from; for a database source, schema.tablename.
destination : dict:
- path : string The schema.tablename to sync to.
advanced_options : dict:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - identity_column : string - row_chunk_size : integer - wipe_destination_table : boolean - truncate_long_lines : boolean - invalid_char_replacement : string - verify_table_row_counts : boolean - partition_column_name : string - partition_schema_name : string - partition_table_name : string - partition_table_partition_column_min_name : string - partition_table_partition_column_max_name : string - last_modified_column : string - mysql_catalog_matches_schema : boolean - first_row_is_header : boolean - export_action : string - sql_query : string - contact_lists : string - soql_query : string
-
Jobs¶
-
class
Jobs(session, return_type='civis')¶ Methods
delete_projects(id, project_id)Remove a Job from a project delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object get(id)Show basic job info get_runs(id, run_id)Check status of a job list(**kwargs)List jobs list_children(id)Show nested tree of children that this job triggers list_parents(id)Show chain of parents as a list that this job triggers from list_projects(id)List the projects a Job belongs to list_shares(id)List users and groups permissioned on this object post_runs(id)Run a job post_trigger_email(id)Generate and retrieve trigger email address put_projects(id, project_id)Add a Job to a project put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object -
delete_projects(id, project_id)¶ Remove a Job from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(id)¶ Show basic job info
Parameters: id : integer
The ID for this job.
Returns: id : integer
name : string
type : string
state : string
Whether the job is idle, queued, running, cancelled, or failed.
created_at : string/date-time
updated_at : string/date-time
runs : list:
Information about the most recent runs of the job. - id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
get_runs(id, run_id)¶ Check status of a job
Parameters: id : integer
The ID of the Job.
run_id : integer
The ID of the Run.
Returns: id : integer
state : string
created_at : string/time
The time that the run was queued.
started_at : string/time
The time that the run started.
finished_at : string/time
The time that the run completed.
error : string
The error message for this run, if present.
-
list(**kwargs)¶ List jobs
Parameters: limit : integer, optional
The maximum number of jobs to return.
state : string, optional
The job’s state. One or more of queued, running, succeeded, failed, and cancelled. Specify multiple values as a comma-separated list (e.g., “A,B”).
type : string, optional
The job’s type. Specify multiple values as a comma-separated list (e.g., “A,B”).
q : string, optional
Query string to search on the id, name, and job type
permission : string, optional
A permissions string, one of “read”, “write”, or “manage”. Lists only jobs for which the current user has that permission.
archived : string, optional
The archival status of the requested object(s).
Returns: id : integer
name : string
type : string
state : string
Whether the job is idle, queued, running, cancelled, or failed.
created_at : string/date-time
updated_at : string/date-time
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
-
list_children(id)¶ Show nested tree of children that this job triggers
Parameters: id : integer
The ID for this job.
Returns: id : integer
name : string
type : string
state : string
created_at : string/date-time
updated_at : string/date-time
runs : list:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
children : list
-
list_parents(id)¶ Show chain of parents as a list that this job triggers from
Parameters: id : integer
The ID for this job.
Returns: id : integer
name : string
type : string
state : string
Whether the job is idle, queued, running, cancelled, or failed.
created_at : string/date-time
updated_at : string/date-time
runs : list:
Information about the most recent runs of the job. - id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
list_projects(id)¶ List the projects a Job belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
post_runs(id)¶ Run a job
Parameters: id : integer
The ID for this job.
Returns: id : integer
state : string
created_at : string/time
The time that the run was queued.
started_at : string/time
The time that the run started.
finished_at : string/time
The time that the run completed.
error : string
The error message for this run, if present.
-
post_trigger_email(id)¶ Generate and retrieve trigger email address
Parameters: id : integer
The ID for this job.
Returns: trigger_email : string
Email address which may be used to trigger this job to run.
-
put_projects(id, project_id)¶ Add a Job to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
Models¶
-
class
Models(session, return_type='civis')¶ Methods
delete_builds(id, build_id)Cancel a build delete_projects(id, project_id)Remove a models from a project delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object get(id)Retrieve model configuration get_builds(id, build_id)Check status of a build list(**kwargs)List models list_builds(id, **kwargs)List builds for the given model list_projects(id)List the projects a models belongs to list_schedules(id)Show the model build schedule list_shares(id)List users and groups permissioned on this object list_types()List all available model types patch(id, **kwargs)Update model configuration post(**kwargs)Create new configuration for a model post_builds(id)Start a build put_archive(id, status)Update the archive status of this object put_predictions(id, table_name, primary_key, ...)Add a table on which to apply the predictive model put_projects(id, project_id)Add a models to a project put_schedules(id, schedule)Schedule the model build put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object -
delete_builds(id, build_id)¶ Cancel a build
Parameters: id : integer
The ID of the model.
build_id : integer
The ID of the build.
Returns: None
Response code 202: success
-
delete_projects(id, project_id)¶ Remove a models from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(id)¶ Retrieve model configuration
Parameters: id : integer
The ID of the model.
Returns: id : integer
The ID of the model.
table_name : string
The qualified name of the table containing the training set from which to build the model.
database_id : integer
The ID of the database holding the training set table used to build the model.
credential_id : integer
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string
The name of the model.
description : string
A description of the model.
interaction_terms : boolean
Whether to search for interaction terms.
box_cox_transformation : boolean
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer
The ID of the model’s type.
primary_key : string
The unique ID (primary key) of the training dataset.
dependent_variable : string
The dependent variable of the training dataset.
dependent_variable_order : list
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
active_build_id : integer
The ID of the current active build, the build used to score predictions.
cross_validation_parameters : dict
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_folds : integer
Number of folds for cross validation. Default value is 5.
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this model.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
time_zone : string
The time zone of this model.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/date-time
The time the model was created.
updated_at : string/date-time
The time the model was updated.
current_build_state : string
The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.
current_build_exception : string
Exception message, if applicable, of the current model build.
builds : list:
A list of trained models available for making predictions. - id : integer The ID of the model build. - name : string The name of the model build. - created_at : string The time the model build was created. - description : string A description of the model build. - root_mean_squared_error : number/float A key metric for continuous models. Nil for other model types. - r_squared_error : number/float A key metric for continuous models. Nil for other model types. - roc_auc : number/float A key metric for binary, multinomial, and ordinal models. Nil for other model types.
predictions : list:
The tables upon which the model will be applied. - id : integer The ID of the model to which to apply the prediction. - table_name : string The qualified name of the table on which to apply the predictive model. - primary_key : list The primary key or composite keys of the table being predicted. - limiting_sql : string A SQL WHERE clause used to scope the rows to be predicted. - output_table : string The qualified name of the table to be created which will contain the model's predictions. - schedule : dict:: - scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour - state : string The status of the prediction. One of: "succeeded", "failed", "queued", or "running,"or "idle", if no build has been attempted.
last_output_location : string
The output JSON for the last build.
archived : string
The archival status of the requested object(s).
-
get_builds(id, build_id)¶ Check status of a build
Parameters: id : integer
The ID of the model.
build_id : integer
The ID of the build.
Returns: id : integer
The ID of the model build.
state : string
The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
error : string
The error, if any, returned by the build.
name : string
The name of the model build.
created_at : string
The time the model build was created.
description : string
A description of the model build.
root_mean_squared_error : number/float
A key metric for continuous models. Nil for other model types.
r_squared_error : number/float
A key metric for continuous models. Nil for other model types.
roc_auc : number/float
A key metric for binary, multinomial, and ordinal models. Nil for other model types.
transformation_metadata : string
A string representing the full JSON output of the metadata for transformation of column names
output : string
A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.
output_location : string
A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.
-
list(**kwargs)¶ List models
Parameters: model_name : string, 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_name : string, 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_variable : string, 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”).
author : string, optional
If specified, return models from this author. It accepts a comma-separated list of author ids.
status : string, optional
If specified, returns models with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, model_name, created_at, name, last_run.updated_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the model.
table_name : string
The qualified name of the table containing the training set from which to build the model.
database_id : integer
The ID of the database holding the training set table used to build the model.
credential_id : integer
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string
The name of the model.
description : string
A description of the model.
interaction_terms : boolean
Whether to search for interaction terms.
box_cox_transformation : boolean
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer
The ID of the model’s type.
primary_key : string
The unique ID (primary key) of the training dataset.
dependent_variable : string
The dependent variable of the training dataset.
dependent_variable_order : list
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
cross_validation_parameters : dict
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_folds : integer
Number of folds for cross validation. Default value is 5.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this model.
time_zone : string
The time zone of this model.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/date-time
The time the model was created.
updated_at : string/date-time
The time the model was updated.
current_build_state : string
The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.
current_build_exception : string
Exception message, if applicable, of the current model build.
builds : list:
A list of trained models available for making predictions. - id : integer The ID of the model build. - name : string The name of the model build. - created_at : string The time the model build was created. - description : string A description of the model build. - root_mean_squared_error : number/float A key metric for continuous models. Nil for other model types. - r_squared_error : number/float A key metric for continuous models. Nil for other model types. - roc_auc : number/float A key metric for binary, multinomial, and ordinal models. Nil for other model types.
predictions : list:
The tables upon which the model will be applied. - id : integer The ID of the model to which to apply the prediction. - table_name : string The qualified name of the table on which to apply the predictive model. - primary_key : list The primary key or composite keys of the table being predicted. - limiting_sql : string A SQL WHERE clause used to scope the rows to be predicted. - output_table : string The qualified name of the table to be created which will contain the model's predictions. - state : string The status of the prediction. One of: "succeeded", "failed", "queued", or "running,"or "idle", if no build has been attempted.
last_output_location : string
The output JSON for the last build.
archived : string
The archival status of the requested object(s).
-
list_builds(id, **kwargs)¶ List builds for the given model
Parameters: id : integer
The ID of the model.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the model build.
state : string
The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
error : string
The error, if any, returned by the build.
name : string
The name of the model build.
created_at : string
The time the model build was created.
description : string
A description of the model build.
root_mean_squared_error : number/float
A key metric for continuous models. Nil for other model types.
r_squared_error : number/float
A key metric for continuous models. Nil for other model types.
roc_auc : number/float
A key metric for binary, multinomial, and ordinal models. Nil for other model types.
transformation_metadata : string
A string representing the full JSON output of the metadata for transformation of column names
output : string
A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.
output_location : string
A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.
-
list_projects(id)¶ List the projects a models belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
-
list_schedules(id)¶ Show the model build schedule
Parameters: id : integer
The ID of the model associated with this schedule.
Returns: id : integer
The ID of the model associated with this schedule.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
list_types()¶ List all available model types
Returns: id : integer
The ID of the model type.
algorithm : string
The name of the algorithm used to train the model.
dv_type : string
The type of dependent variable predicted by the model.
fint_allowed : boolean
Whether this model type supports searching for interaction terms.
-
patch(id, **kwargs)¶ Update model configuration
Parameters: id : integer
The ID of the model.
table_name : string, optional
The qualified name of the table containing the training set from which to build the model.
database_id : integer, optional
The ID of the database holding the training set table used to build the model.
credential_id : integer, optional
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string, optional
The name of the model.
description : string, optional
A description of the model.
interaction_terms : boolean, optional
Whether to search for interaction terms.
box_cox_transformation : boolean, optional
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer, optional
The ID of the model’s type.
primary_key : string, optional
The unique ID (primary key) of the training dataset.
dependent_variable : string, optional
The dependent variable of the training dataset.
dependent_variable_order : list, optional
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list, optional
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string, optional
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
active_build_id : integer, optional
The ID of the current active build, the build used to score predictions.
cross_validation_parameters : dict, optional
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_folds : integer, optional
Number of folds for cross validation. Default value is 5.
notifications : dict, optional:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer, optional
The ID of the parent job that will trigger this model.
time_zone : string, optional
The time zone of this model.
Returns: None
Response code 204: success
-
post(**kwargs)¶ Create new configuration for a model
Parameters: table_name : string, optional
The qualified name of the table containing the training set from which to build the model.
database_id : integer, optional
The ID of the database holding the training set table used to build the model.
credential_id : integer, optional
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string, optional
The name of the model.
description : string, optional
A description of the model.
interaction_terms : boolean, optional
Whether to search for interaction terms.
box_cox_transformation : boolean, optional
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer, optional
The ID of the model’s type.
primary_key : string, optional
The unique ID (primary key) of the training dataset.
dependent_variable : string, optional
The dependent variable of the training dataset.
dependent_variable_order : list, optional
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list, optional
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string, optional
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
active_build_id : integer, optional
The ID of the current active build, the build used to score predictions.
cross_validation_parameters : dict, optional
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_folds : integer, optional
Number of folds for cross validation. Default value is 5.
notifications : dict, optional:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer, optional
The ID of the parent job that will trigger this model.
time_zone : string, optional
The time zone of this model.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: id : integer
The ID of the model.
table_name : string
The qualified name of the table containing the training set from which to build the model.
database_id : integer
The ID of the database holding the training set table used to build the model.
credential_id : integer
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string
The name of the model.
description : string
A description of the model.
interaction_terms : boolean
Whether to search for interaction terms.
box_cox_transformation : boolean
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer
The ID of the model’s type.
primary_key : string
The unique ID (primary key) of the training dataset.
dependent_variable : string
The dependent variable of the training dataset.
dependent_variable_order : list
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
active_build_id : integer
The ID of the current active build, the build used to score predictions.
cross_validation_parameters : dict
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_folds : integer
Number of folds for cross validation. Default value is 5.
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this model.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
time_zone : string
The time zone of this model.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/date-time
The time the model was created.
updated_at : string/date-time
The time the model was updated.
current_build_state : string
The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.
current_build_exception : string
Exception message, if applicable, of the current model build.
builds : list:
A list of trained models available for making predictions. - id : integer The ID of the model build. - name : string The name of the model build. - created_at : string The time the model build was created. - description : string A description of the model build. - root_mean_squared_error : number/float A key metric for continuous models. Nil for other model types. - r_squared_error : number/float A key metric for continuous models. Nil for other model types. - roc_auc : number/float A key metric for binary, multinomial, and ordinal models. Nil for other model types.
predictions : list:
The tables upon which the model will be applied. - id : integer The ID of the model to which to apply the prediction. - table_name : string The qualified name of the table on which to apply the predictive model. - primary_key : list The primary key or composite keys of the table being predicted. - limiting_sql : string A SQL WHERE clause used to scope the rows to be predicted. - output_table : string The qualified name of the table to be created which will contain the model's predictions. - schedule : dict:: - scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour - state : string The status of the prediction. One of: "succeeded", "failed", "queued", or "running,"or "idle", if no build has been attempted.
last_output_location : string
The output JSON for the last build.
archived : string
The archival status of the requested object(s).
-
post_builds(id)¶ Start a build
Parameters: id : integer
The ID of the model.
Returns: id : integer
The ID of the model build.
state : string
The state of the model build.one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
error : string
The error, if any, returned by the build.
name : string
The name of the model build.
created_at : string
The time the model build was created.
description : string
A description of the model build.
root_mean_squared_error : number/float
A key metric for continuous models. Nil for other model types.
r_squared_error : number/float
A key metric for continuous models. Nil for other model types.
roc_auc : number/float
A key metric for binary, multinomial, and ordinal models. Nil for other model types.
transformation_metadata : string
A string representing the full JSON output of the metadata for transformation of column names
output : string
A string representing the JSON output for the specified build. Only present when smaller than 10KB in size.
output_location : string
A URL representing the location of the full JSON output for the specified build.The URL link will be valid for 5 minutes.
-
put_archive(id, status)¶ Update the archive status of this object
Parameters: id : integer
The ID of the object.
status : boolean
The desired archived status of the object.
Returns: id : integer
The ID of the model.
table_name : string
The qualified name of the table containing the training set from which to build the model.
database_id : integer
The ID of the database holding the training set table used to build the model.
credential_id : integer
The ID of the credential used to read the target table. Defaults to the user’s default credential.
model_name : string
The name of the model.
description : string
A description of the model.
interaction_terms : boolean
Whether to search for interaction terms.
box_cox_transformation : boolean
Whether to transform data so that it assumes a normal distribution. Valid only with continuous models.
model_type_id : integer
The ID of the model’s type.
primary_key : string
The unique ID (primary key) of the training dataset.
dependent_variable : string
The dependent variable of the training dataset.
dependent_variable_order : list
The order of dependent variables, especially useful for Ordinal Modeling.
excluded_columns : list
A list of columns which will be considered ineligible to be independent variables.
limiting_sql : string
A custom SQL WHERE clause used to filter the rows used to build the model. (e.g., “id > 105”).
active_build_id : integer
The ID of the current active build, the build used to score predictions.
cross_validation_parameters : dict
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_folds : integer
Number of folds for cross validation. Default value is 5.
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this model.
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
time_zone : string
The time zone of this model.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/date-time
The time the model was created.
updated_at : string/date-time
The time the model was updated.
current_build_state : string
The status of the current model build. One of “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.
current_build_exception : string
Exception message, if applicable, of the current model build.
builds : list:
A list of trained models available for making predictions. - id : integer The ID of the model build. - name : string The name of the model build. - created_at : string The time the model build was created. - description : string A description of the model build. - root_mean_squared_error : number/float A key metric for continuous models. Nil for other model types. - r_squared_error : number/float A key metric for continuous models. Nil for other model types. - roc_auc : number/float A key metric for binary, multinomial, and ordinal models. Nil for other model types.
predictions : list:
The tables upon which the model will be applied. - id : integer The ID of the model to which to apply the prediction. - table_name : string The qualified name of the table on which to apply the predictive model. - primary_key : list The primary key or composite keys of the table being predicted. - limiting_sql : string A SQL WHERE clause used to scope the rows to be predicted. - output_table : string The qualified name of the table to be created which will contain the model's predictions. - schedule : dict:: - scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour - state : string The status of the prediction. One of: "succeeded", "failed", "queued", or "running,"or "idle", if no build has been attempted.
last_output_location : string
The output JSON for the last build.
archived : string
The archival status of the requested object(s).
-
put_predictions(id, table_name, primary_key, **kwargs)¶ Add a table on which to apply the predictive model
Parameters: id : integer
The ID of the model to which to apply the prediction.
table_name : string
The qualified name of the table on which to apply the predictive model.
primary_key : list
The primary key or composite keys of the table being predicted.
limiting_sql : string, optional
A SQL WHERE clause used to scope the rows to be predicted.
output_table : string, optional
The qualified name of the table to be created which will contain the model’s predictions.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
Returns: id : integer
The ID of the model to which to apply the prediction.
table_name : string
The qualified name of the table on which to apply the predictive model.
primary_key : list
The primary key or composite keys of the table being predicted.
limiting_sql : string
A SQL WHERE clause used to scope the rows to be predicted.
output_table : string
The qualified name of the table to be created which will contain the model’s predictions.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
state : string
The status of the prediction. One of: “succeeded”, “failed”, “queued”, or “running,”or “idle”, if no build has been attempted.
-
put_projects(id, project_id)¶ Add a models to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
put_schedules(id, schedule)¶ Schedule the model build
Parameters: id : integer
The ID of the model associated with this schedule.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
Returns: id : integer
The ID of the model associated with this schedule.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
Predictions¶
-
class
Predictions(session, return_type='civis')¶ Methods
delete_runs(id, run_id)Cancel a run get(id)Show the specified prediction get_runs(id, run_id)Check status of a run list(**kwargs)List predictions list_runs(id, **kwargs)List runs for the given prediction list_schedules(id)Show the prediction schedule patch(id, **kwargs)Update a prediction post_runs(id)Start a run put_schedules(id, **kwargs)Schedule the prediction -
delete_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the prediction.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
-
get(id)¶ Show the specified prediction
Parameters: id : integer
The ID of the prediction.
Returns: id : integer
The ID of the prediction.
model_id : integer
The ID of the model used for this prediction.
scored_table_id : integer
The ID of the source table for this prediction.
scored_table_name : string
The name of the source table for this prediction.
output_table_name : string
The name of the output table for this prediction.
state : string
The state of the last run of this prediction.
error : string
The error, if any, of the last run of this prediction.
started_at : string/date-time
The start time of the last run of this prediction.
finished_at : string/date-time
The end time of the last run of this prediction.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
scored_tables : list:
An array of created prediction tables. - id : integer The ID of the table with created predictions. - schema : string The schema of table with created predictions. - name : string The name of table with created predictions. - created_at : string/date-time The time when the table with created predictions was created. - score_stats : list:: An array of metrics on the created predictions. - score_name : string The name of the score. - histogram : list The histogram of the distribution of scores. - avg_score : number/float The average score. - min_score : number/float The minimum score. - max_score : number/float The maximum score.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
limiting_sql : string
A SQL WHERE clause used to scope the rows to be predicted.
primary_key : list
The primary key or composite keys of the table being predicted.
-
get_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the prediction.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the prediction run.
prediction_id : integer
The ID of the prediction.
state : string
The state of the prediction run.
exception : string
The exception, if any, returned by the prediction run.
name : string
The name of table created by this predictions run.
created_at : string/date-time
The time when the table with created predictions was created.
score_stats : list:
An array of metrics on the created predictions. - score_name : string The name of the score. - histogram : list The histogram of the distribution of scores. - avg_score : number/float The average score. - min_score : number/float The minimum score. - max_score : number/float The maximum score.
-
list(**kwargs)¶ List predictions
Parameters: model_id : integer, optional
If specified, only return predictions associated with this model ID.
Returns: id : integer
The ID of the prediction.
model_id : integer
The ID of the model used for this prediction.
scored_table_id : integer
The ID of the source table for this prediction.
scored_table_name : string
The name of the source table for this prediction.
output_table_name : string
The name of the output table for this prediction.
state : string
The state of the last run of this prediction.
error : string
The error, if any, of the last run of this prediction.
started_at : string/date-time
The start time of the last run of this prediction.
finished_at : string/date-time
The end time of the last run of this prediction.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
-
list_runs(id, **kwargs)¶ List runs for the given prediction
Parameters: id : integer
The ID of the prediction.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the prediction run.
prediction_id : integer
The ID of the prediction.
state : string
The state of the prediction run.
exception : string
The exception, if any, returned by the prediction run.
name : string
The name of table created by this predictions run.
created_at : string/date-time
The time when the table with created predictions was created.
score_stats : list:
An array of metrics on the created predictions. - score_name : string The name of the score. - histogram : list The histogram of the distribution of scores. - avg_score : number/float The average score. - min_score : number/float The minimum score. - max_score : number/float The maximum score.
-
list_schedules(id)¶ Show the prediction schedule
Parameters: id : integer
ID of the prediction associated with this schedule.
Returns: id : integer
ID of the prediction associated with this schedule.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
score_on_model_build : boolean
Whether the prediction will run after a rebuild of the associated model.
-
patch(id, **kwargs)¶ Update a prediction
Parameters: id : integer
The ID of the prediction.
output_table_name : string, optional
The name of the output table for this prediction.
limiting_sql : string, optional
A SQL WHERE clause used to scope the rows to be predicted.
primary_key : list, optional
The primary key or composite keys of the table being predicted.
Returns: id : integer
The ID of the prediction.
model_id : integer
The ID of the model used for this prediction.
scored_table_id : integer
The ID of the source table for this prediction.
scored_table_name : string
The name of the source table for this prediction.
output_table_name : string
The name of the output table for this prediction.
state : string
The state of the last run of this prediction.
error : string
The error, if any, of the last run of this prediction.
started_at : string/date-time
The start time of the last run of this prediction.
finished_at : string/date-time
The end time of the last run of this prediction.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
scored_tables : list:
An array of created prediction tables. - id : integer The ID of the table with created predictions. - schema : string The schema of table with created predictions. - name : string The name of table with created predictions. - created_at : string/date-time The time when the table with created predictions was created. - score_stats : list:: An array of metrics on the created predictions. - score_name : string The name of the score. - histogram : list The histogram of the distribution of scores. - avg_score : number/float The average score. - min_score : number/float The minimum score. - max_score : number/float The maximum score.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
limiting_sql : string
A SQL WHERE clause used to scope the rows to be predicted.
primary_key : list
The primary key or composite keys of the table being predicted.
-
post_runs(id)¶ Start a run
Parameters: id : integer
The ID of the prediction.
Returns: id : integer
The ID of the prediction run.
prediction_id : integer
The ID of the prediction.
state : string
The state of the prediction run.
exception : string
The exception, if any, returned by the prediction run.
name : string
The name of table created by this predictions run.
created_at : string/date-time
The time when the table with created predictions was created.
score_stats : list:
An array of metrics on the created predictions. - score_name : string The name of the score. - histogram : list The histogram of the distribution of scores. - avg_score : number/float The average score. - min_score : number/float The minimum score. - max_score : number/float The maximum score.
-
put_schedules(id, **kwargs)¶ Schedule the prediction
Parameters: id : integer
ID of the prediction associated with this schedule.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
score_on_model_build : boolean, optional
Whether the prediction will run after a rebuild of the associated model.
Returns: id : integer
ID of the prediction associated with this schedule.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
score_on_model_build : boolean
Whether the prediction will run after a rebuild of the associated model.
-
Projects¶
-
class
Projects(session, return_type='civis')¶ Methods
delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object get(project_id)Get a detailed view of a project and the objects in it list(**kwargs)List projects list_shares(id)List users and groups permissioned on this object post(name, description, **kwargs)Create a project put(project_id, **kwargs)Update a project put_archive(id, status)Update the archive status of this object put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(project_id)¶ Get a detailed view of a project and the objects in it
Parameters: project_id : integer
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
tables : list:
- schema : string - name : string - row_count : integer - column_count : integer - created_at : string/time - updated_at : string/time
surveys : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time
scripts : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
imports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
models : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
reports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
script_templates : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string
files : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - file_name : string - file_size : integer
app_instances : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - slug : string
all_objects : list:
- project_id : integer - object_id : integer - object_type : string - fco_type : string - sub_type : string - name : string - icon : string - author : string - archived : string The archival status of the requested object(s).
note : string
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
list(**kwargs)¶ List projects
Parameters: author : string, optional
If specified, return projects owned by this author. It accepts a comma- separated list of author ids.
permission : string, optional
A permissions string, one of “read”, “write”, or “manage”. Lists only projects for which the current user has that permission.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 1000.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
post(name, description, **kwargs)¶ Create a project
Parameters: name : string
The name of this project.
description : string
A description of the project
note : string, optional
Notes for the project
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
tables : list:
- schema : string - name : string - row_count : integer - column_count : integer - created_at : string/time - updated_at : string/time
surveys : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time
scripts : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
imports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
models : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
reports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
script_templates : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string
files : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - file_name : string - file_size : integer
app_instances : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - slug : string
all_objects : list:
- project_id : integer - object_id : integer - object_type : string - fco_type : string - sub_type : string - name : string - icon : string - author : string - archived : string The archival status of the requested object(s).
note : string
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
put(project_id, **kwargs)¶ Update a project
Parameters: project_id : integer
name : string, optional
The name of this project.
description : string, optional
A description of the project
note : string, optional
Notes for the project
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
tables : list:
- schema : string - name : string - row_count : integer - column_count : integer - created_at : string/time - updated_at : string/time
surveys : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time
scripts : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
imports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
models : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
reports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
script_templates : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string
files : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - file_name : string - file_size : integer
app_instances : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - slug : string
all_objects : list:
- project_id : integer - object_id : integer - object_type : string - fco_type : string - sub_type : string - name : string - icon : string - author : string - archived : string The archival status of the requested object(s).
note : string
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
-
put_archive(id, status)¶ Update the archive status of this object
Parameters: id : integer
The ID of the object.
status : boolean
The desired archived status of the object.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
tables : list:
- schema : string - name : string - row_count : integer - column_count : integer - created_at : string/time - updated_at : string/time
surveys : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time
scripts : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
imports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - type : string - finished_at : string/time - state : string
models : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
reports : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - state : string
script_templates : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string
files : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - file_name : string - file_size : integer
app_instances : list:
- id : integer The object ID. - created_at : string/time - updated_at : string/time - name : string - slug : string
all_objects : list:
- project_id : integer - object_id : integer - object_type : string - fco_type : string - sub_type : string - name : string - icon : string - author : string - archived : string The archival status of the requested object(s).
note : string
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Queries¶
-
class
Queries(session, return_type='civis')¶ Methods
delete_runs(id, run_id)Cancel a run get(id)Get details about a query get_runs(id, run_id)Check status of a run list(**kwargs)List all queries list_runs(id, **kwargs)List runs for the given query post(database, sql, preview_rows, **kwargs)Execute a query post_runs(id)Start a run put_scripts(id, script_id)Update the query’s associated script -
delete_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the query.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
-
get(id)¶ Get details about a query
Parameters: id : integer
The query ID.
Returns: id : integer
The query ID.
database : integer
The database ID.
sql : string
The SQL to execute.
credential : integer
The credential ID.
result_rows : list
A preview of rows returned by the query.
result_columns : list
A preview of columns returned by the query.
script_id : integer
The ID of the script associated with this query.
exception : string
Exception returned from the query, null if the query was a success.
created_at : string/time
updated_at : string/time
finished_at : string/date-time
The end time of the last run.
state : string
The state of the last run.
last_run_id : integer
The ID of the last run.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
name : string
The name of the query.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
started_at : string/date-time
The start time of the last run.
report_id : integer
The ID of the report associated with this query.
-
get_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the query.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
query_id : integer
The ID of the query.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list(**kwargs)¶ List all queries
Parameters: database_id : integer, optional
The database ID.
author_id : integer, optional
The author of the query.
created_before : string, optional
An upper bound for the creation date of the query.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to created_at. Must be one of: created_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The query ID.
database : integer
The database ID.
sql : string
The SQL to execute.
credential : integer
The credential ID.
result_rows : list
A preview of rows returned by the query.
result_columns : list
A preview of columns returned by the query.
script_id : integer
The ID of the script associated with this query.
exception : string
Exception returned from the query, null if the query was a success.
created_at : string/time
updated_at : string/time
finished_at : string/date-time
The end time of the last run.
state : string
The state of the last run.
last_run_id : integer
The ID of the last run.
preview_rows : integer
The number of rows to save from the query’s result (maximum: 100).
started_at : string/date-time
The start time of the last run.
report_id : integer
The ID of the report associated with this query.
-
list_runs(id, **kwargs)¶ List runs for the given query
Parameters: id : integer
The ID of the query.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the run.
query_id : integer
The ID of the query.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
post(database, sql, preview_rows, **kwargs)¶ Execute a query
Parameters: database : integer
The database ID.
sql : string
The SQL to execute.
preview_rows : integer
The number of rows to save from the query’s result (maximum: 100).
credential : integer, optional
The credential ID.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
interactive : boolean, optional
Deprecated and not used.
include_header : boolean, optional
Whether the CSV output should include a header row [default: true].
compression : string, optional
The type of compression. One of gzip or zip, or none [default: gzip].
column_delimiter : string, optional
The delimiter to use. One of comma or tab, or pipe [default: comma].
unquoted : boolean, optional
If true, will not quote fields.
filename_prefix : string, optional
The output filename prefix.
Returns: id : integer
The query ID.
database : integer
The database ID.
sql : string
The SQL to execute.
credential : integer
The credential ID.
result_rows : list
A preview of rows returned by the query.
result_columns : list
A preview of columns returned by the query.
script_id : integer
The ID of the script associated with this query.
exception : string
Exception returned from the query, null if the query was a success.
created_at : string/time
updated_at : string/time
finished_at : string/date-time
The end time of the last run.
state : string
The state of the last run.
last_run_id : integer
The ID of the last run.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
interactive : boolean
Deprecated and not used.
preview_rows : integer
The number of rows to save from the query’s result (maximum: 100).
include_header : boolean
Whether the CSV output should include a header row [default: true].
compression : string
The type of compression. One of gzip or zip, or none [default: gzip].
column_delimiter : string
The delimiter to use. One of comma or tab, or pipe [default: comma].
unquoted : boolean
If true, will not quote fields.
filename_prefix : string
The output filename prefix.
started_at : string/date-time
The start time of the last run.
report_id : integer
The ID of the report associated with this query.
-
post_runs(id)¶ Start a run
Parameters: id : integer
The ID of the query.
Returns: id : integer
The ID of the run.
query_id : integer
The ID of the query.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
put_scripts(id, script_id)¶ Update the query’s associated script
Parameters: id : integer
The query ID.
script_id : integer
The ID of the script associated with this query.
Returns: id : integer
The query ID.
database : integer
The database ID.
sql : string
The SQL to execute.
credential : integer
The credential ID.
result_rows : list
A preview of rows returned by the query.
result_columns : list
A preview of columns returned by the query.
script_id : integer
The ID of the script associated with this query.
exception : string
Exception returned from the query, null if the query was a success.
created_at : string/time
updated_at : string/time
finished_at : string/date-time
The end time of the last run.
state : string
The state of the last run.
last_run_id : integer
The ID of the last run.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
name : string
The name of the query.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
started_at : string/date-time
The start time of the last run.
report_id : integer
The ID of the report associated with this query.
-
Reports¶
-
class
Reports(session, return_type='civis')¶ Methods
delete_grants(id)Revoke permisstion for this report to perform Civis platform API operations on delete_projects(id, project_id)Remove a Report from a project delete_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_shares_users(id, user_id)Revoke the permissions a user has on this object get(id)Show a single report list(**kwargs)List the reports visible to the current user list_projects(id)List the projects a Report belongs to list_shares(id)List users and groups permissioned on this object list_snapshots(id)Get details about the report’s snapshot automation settings patch(id, **kwargs)Update a report patch_snapshots(id, **kwargs)Update the report’s snapshot automation settings post(**kwargs)Create a report post_grants(id)Grant this report the ability to perform Civis platform API operations on your post_snapshots(id, **kwargs)Generate and optionally email a snapshot of the specified report put_archive(id, status)Update the archive status of this object put_projects(id, project_id)Add a Report to a project put_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_shares_users(id, user_ids, permission_level)Set the permissions users have on this object -
delete_grants(id)¶ Revoke permisstion for this report to perform Civis platform API operations on your behalf
Parameters: id : integer
The ID of this report.
Returns: None
Response code 204: success
-
delete_projects(id, project_id)¶ Remove a Report from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(id)¶ Show a single report
Parameters: id : integer
The ID of this report.
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
auth_data_url : string
auth_code_url : string
config : string
Any configuration metadata for this report.
valid_output_file : boolean
Whether the job (a script or a query) that backs the report currently has a valid output file.
provide_api_key : boolean
Whether the report requests an API Key from the report viewer.
api_key : string
A Civis API key that can be used by this report.
api_key_id : integer
The ID of the API key. Can be used for auditing API use by this report.
app_state : dict
Any application state blob for this report.
-
list(**kwargs)¶ List the reports visible to the current user
Parameters: type : string, optional
If specified, return report of these types. It accepts a comma-separated list, possible values are ‘tableau’, ‘other’.
author : string, optional
If specified, return reports from this author. It accepts a comma-separated list of author ids.
template_id : integer, optional
If specified, return reports using the provided Template.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
-
list_projects(id)¶ List the projects a Report belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
list_snapshots(id)¶ Get details about the report’s snapshot automation settings
Parameters: id : integer
The ID of this report.
Returns: id : integer
The ID of this report.
state : string
The status of the job’s last run.
finished_at : string/time
The time that the job’s last run finished.
send_email_on_completion : boolean
Whether the job will send emails on completion.
email_template : string
Custom email template.
recipient_email_addresses : string
Email addresses to send report to, comma separated.
email_subject : string
Subject for Email.
height : integer
The height of the cropped snapshot image in screen pixels. The default value is 900 pixels. Minimum value is 600 pixels.
width : integer
The width of the cropped snapshot image in screen pixels. The default value is 1440 pixels. Minimum value is 600 pixels.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this snapshot.
-
patch(id, **kwargs)¶ Update a report
Parameters: id : integer
The ID of the report to modify.
name : string, optional
The name of the report.
script_id : integer, optional
The ID of the job (a script or a query) used to create this report.
code_body : string, optional
The code for the report visualization.
config : string, optional
app_state : dict, optional
The application state blob for this report.
provide_api_key : boolean, optional
Allow the report to provide an API key to front-end code.
template_id : integer, optional
The ID of the template used for this report. If null is passed, no template will back this report. Changes to the backing template will reset the report appState.
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
auth_data_url : string
auth_code_url : string
config : string
Any configuration metadata for this report.
valid_output_file : boolean
Whether the job (a script or a query) that backs the report currently has a valid output file.
provide_api_key : boolean
Whether the report requests an API Key from the report viewer.
api_key : string
A Civis API key that can be used by this report.
api_key_id : integer
The ID of the API key. Can be used for auditing API use by this report.
app_state : dict
Any application state blob for this report.
-
patch_snapshots(id, **kwargs)¶ Update the report’s snapshot automation settings
Parameters: id : integer
The ID of this report.
state : string, optional
The status of the job’s last run.
finished_at : string/time, optional
The time that the job’s last run finished.
send_email_on_completion : boolean, optional
Whether the job will send emails on completion.
email_template : string, optional
Custom email template.
recipient_email_addresses : string, optional
Email addresses to send report to, comma separated.
email_subject : string, optional
Subject for Email.
height : integer, optional
The height of the cropped snapshot image in screen pixels. The default value is 900 pixels. Minimum value is 600 pixels.
width : integer, optional
The width of the cropped snapshot image in screen pixels. The default value is 1440 pixels. Minimum value is 600 pixels.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer, optional
The ID of the parent job that will trigger this snapshot.
Returns: id : integer
The ID of this report.
state : string
The status of the job’s last run.
finished_at : string/time
The time that the job’s last run finished.
send_email_on_completion : boolean
Whether the job will send emails on completion.
email_template : string
Custom email template.
recipient_email_addresses : string
Email addresses to send report to, comma separated.
email_subject : string
Subject for Email.
height : integer
The height of the cropped snapshot image in screen pixels. The default value is 900 pixels. Minimum value is 600 pixels.
width : integer
The width of the cropped snapshot image in screen pixels. The default value is 1440 pixels. Minimum value is 600 pixels.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this snapshot.
-
post(**kwargs)¶ Create a report
Parameters: script_id : integer, optional
The ID of the job (a script or a query) used to create this report.
name : string, optional
The name of the report.
code_body : string, optional
The code for the report visualization.
app_state : dict, optional
Any application state blob for this report.
provide_api_key : boolean, optional
Allow the report to provide an API key to front-end code.
template_id : integer, optional
The ID of the template used for this report.
hidden : boolean, optional
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
auth_data_url : string
auth_code_url : string
config : string
Any configuration metadata for this report.
valid_output_file : boolean
Whether the job (a script or a query) that backs the report currently has a valid output file.
provide_api_key : boolean
Whether the report requests an API Key from the report viewer.
api_key : string
A Civis API key that can be used by this report.
api_key_id : integer
The ID of the API key. Can be used for auditing API use by this report.
app_state : dict
Any application state blob for this report.
-
post_grants(id)¶ Grant this report the ability to perform Civis platform API operations on your behalf
Parameters: id : integer
The ID of this report.
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
auth_data_url : string
auth_code_url : string
config : string
Any configuration metadata for this report.
valid_output_file : boolean
Whether the job (a script or a query) that backs the report currently has a valid output file.
provide_api_key : boolean
Whether the report requests an API Key from the report viewer.
api_key : string
A Civis API key that can be used by this report.
api_key_id : integer
The ID of the API key. Can be used for auditing API use by this report.
app_state : dict
Any application state blob for this report.
-
post_snapshots(id, **kwargs)¶ Generate and optionally email a snapshot of the specified report
Parameters: id : integer
The ID of this report.
state : string, optional
The status of the job’s last run.
finished_at : string/time, optional
The time that the job’s last run finished.
send_email_on_completion : boolean, optional
Whether the job will send emails on completion.
email_template : string, optional
Custom email template.
recipient_email_addresses : string, optional
Email addresses to send report to, comma separated.
email_subject : string, optional
Subject for Email.
height : integer, optional
The height of the cropped snapshot image in screen pixels. The default value is 900 pixels. Minimum value is 600 pixels.
width : integer, optional
The width of the cropped snapshot image in screen pixels. The default value is 1440 pixels. Minimum value is 600 pixels.
schedule : dict, optional:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer, optional
The ID of the parent job that will trigger this snapshot.
Returns: id : integer
The ID of this report.
state : string
The status of the job’s last run.
finished_at : string/time
The time that the job’s last run finished.
send_email_on_completion : boolean
Whether the job will send emails on completion.
email_template : string
Custom email template.
recipient_email_addresses : string
Email addresses to send report to, comma separated.
email_subject : string
Subject for Email.
height : integer
The height of the cropped snapshot image in screen pixels. The default value is 900 pixels. Minimum value is 600 pixels.
width : integer
The width of the cropped snapshot image in screen pixels. The default value is 1440 pixels. Minimum value is 600 pixels.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
parent_id : integer
The ID of the parent job that will trigger this snapshot.
-
put_archive(id, status)¶ Update the archive status of this object
Parameters: id : integer
The ID of the object.
status : boolean
The desired archived status of the object.
Returns: id : integer
The ID of this report.
name : string
The name of the report.
user : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
created_at : string/time
updated_at : string/time
projects : list:
A list of projects containing the report. - id : integer The ID for the project. - name : string The name of the project.
state : string
The status of the report’s last run.
finished_at : string/time
The time that the report’s last run finished.
viz_updated_at : string/time
The time that the report’s visualization was last updated.
script : dict:
- id : integer The ID for the script. - name : string The name of the script. - sql : string The raw SQL query for the script.
job_path : string
The link to details of the job that backs this report.
tableau_id : integer
template_id : integer
The ID of the template used for this report.
auth_thumbnail_url : string
URL for a thumbnail of the report.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
auth_data_url : string
auth_code_url : string
config : string
Any configuration metadata for this report.
valid_output_file : boolean
Whether the job (a script or a query) that backs the report currently has a valid output file.
provide_api_key : boolean
Whether the report requests an API Key from the report viewer.
api_key : string
A Civis API key that can be used by this report.
api_key_id : integer
The ID of the API key. Can be used for auditing API use by this report.
app_state : dict
Any application state blob for this report.
-
put_projects(id, project_id)¶ Add a Report to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
Set the permissions users have on this object
Parameters: id : integer
ID of the resource to be shared
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
Scripts¶
-
class
Scripts(session, return_type='civis')¶ Methods
delete_containers_projects(id, project_id)Remove a container docker from a project delete_containers_runs(id, run_id)Cancel a run delete_containers_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_containers_shares_users(id, user_id)Revoke the permissions a user has on this object delete_custom_projects(id, project_id)Remove a Job from a project delete_custom_runs(id, run_id)Cancel a run delete_custom_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_custom_shares_users(id, user_id)Revoke the permissions a user has on this object delete_javascript_projects(id, project_id)Remove a scripted sql from a project delete_javascript_runs(id, run_id)Cancel a run delete_javascript_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_javascript_shares_users(id, user_id)Revoke the permissions a user has on this object delete_python3_projects(id, project_id)Remove a python docker from a project delete_python3_runs(id, run_id)Cancel a run delete_python3_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_python3_shares_users(id, user_id)Revoke the permissions a user has on this object delete_r_projects(id, project_id)Remove a r docker from a project delete_r_runs(id, run_id)Cancel a run delete_r_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_r_shares_users(id, user_id)Revoke the permissions a user has on this object delete_sql_projects(id, project_id)Remove a scripts from a project delete_sql_runs(id, run_id)Cancel a run delete_sql_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_sql_shares_users(id, user_id)Revoke the permissions a user has on this object get(id)Get details about a script get_containers(id)View a container get_containers_runs(id, run_id)Check status of a run get_custom(id)Get a CustomScript get_custom_runs(id, run_id)Check status of a run get_javascript(id)Get a JavaScript Script get_javascript_runs(id, run_id)Check status of a run get_python3(id)Get a Python Script get_python3_runs(id, run_id)Check status of a run get_r(id)Get an R Script get_r_runs(id, run_id)Check status of a run get_sql(id)Get a SQL script get_sql_runs(id, run_id)Check status of a run list(**kwargs)List scripts list_containers_projects(id)List the projects a container docker belongs to list_containers_runs(id, **kwargs)List runs for the given container list_containers_runs_logs(id, run_id, **kwargs)Get the logs for a run list_containers_runs_outputs(id, run_id, ...)List the outputs for a run list_containers_shares(id)List users and groups permissioned on this object list_custom(**kwargs)List Custom Scripts list_custom_projects(id)List the projects a Job belongs to list_custom_runs(id, **kwargs)List runs for the given custom list_custom_runs_logs(id, run_id, **kwargs)Get the logs for a run list_custom_runs_outputs(id, run_id, **kwargs)List the outputs for a run list_custom_shares(id)List users and groups permissioned on this object list_history(id)Get the run history and outputs of this script list_javascript_projects(id)List the projects a scripted sql belongs to list_javascript_runs(id, **kwargs)List runs for the given javascript list_javascript_runs_logs(id, run_id, **kwargs)Get the logs for a run list_javascript_runs_outputs(id, run_id, ...)List the outputs for a run list_javascript_shares(id)List users and groups permissioned on this object list_python3_projects(id)List the projects a python docker belongs to list_python3_runs(id, **kwargs)List runs for the given python list_python3_runs_logs(id, run_id, **kwargs)Get the logs for a run list_python3_runs_outputs(id, run_id, **kwargs)List the outputs for a run list_python3_shares(id)List users and groups permissioned on this object list_r_projects(id)List the projects a r docker belongs to list_r_runs(id, **kwargs)List runs for the given r list_r_runs_logs(id, run_id, **kwargs)Get the logs for a run list_r_runs_outputs(id, run_id, **kwargs)List the outputs for a run list_r_shares(id)List users and groups permissioned on this object list_sql_projects(id)List the projects a scripts belongs to list_sql_runs(id, **kwargs)List runs for the given sql list_sql_runs_logs(id, run_id, **kwargs)Get the logs for a run list_sql_runs_outputs(id, run_id, **kwargs)List the outputs for a run list_sql_shares(id)List users and groups permissioned on this object list_types()List available script types patch(id, **kwargs)Update a script patch_containers(id, **kwargs)Update a container patch_containers_runs(id, run_id, **kwargs)Update a run patch_custom(id, **kwargs)Update some attributes of this CustomScript patch_javascript(id, **kwargs)Update some attributes of this JavaScript Script patch_python3(id, **kwargs)Update some attributes of this Python Script patch_r(id, **kwargs)Update some attributes of this R Script patch_sql(id, **kwargs)Update some attributes of this SQL script post(name, remote_host_id, credential_id, ...)Create a script post_cancel(id)Cancel a run post_containers(required_resources, ...)Create a container post_containers_runs(id)Start a run post_containers_runs_heartbeats(id, run_id)Indicate that the given run is being handled post_containers_runs_logs(id, run_id, **kwargs)Add log messages post_containers_runs_outputs(id, run_id, ...)Add an output for a run post_custom(from_template_id, **kwargs)Create a CustomScript post_custom_runs(id)Start a run post_custom_runs_outputs(id, run_id, ...)Add an output for a run post_javascript(name, source, ...)Create a JavaScript Script post_javascript_runs(id)Start a run post_javascript_runs_outputs(id, run_id, ...)Add an output for a run post_python3(name, source, **kwargs)Create a Python Script post_python3_runs(id)Start a run post_python3_runs_outputs(id, run_id, ...)Add an output for a run post_r(name, source, **kwargs)Create an R Script post_r_runs(id)Start a run post_r_runs_outputs(id, run_id, object_type, ...)Add an output for a run post_run(id)Run a script post_sql(name, sql, remote_host_id, ...)Create a SQL script post_sql_runs(id)Start a run put_containers(id, required_resources, ...)Edit a container put_containers_archive(id, status)Update the archive status of this object put_containers_projects(id, project_id)Add a container docker to a project put_containers_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_containers_shares_users(id, user_ids, ...)Set the permissions users have on this object put_custom(id, **kwargs)Replace all attributes of this CustomScript put_custom_archive(id, status)Update the archive status of this object put_custom_projects(id, project_id)Add a Job to a project put_custom_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_custom_shares_users(id, user_ids, ...)Set the permissions users have on this object put_javascript(id, name, source, ...)Replace all attributes of this JavaScript Script put_javascript_archive(id, status)Update the archive status of this object put_javascript_projects(id, project_id)Add a scripted sql to a project put_javascript_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_javascript_shares_users(id, user_ids, ...)Set the permissions users have on this object put_python3(id, name, source, **kwargs)Replace all attributes of this Python Script put_python3_archive(id, status)Update the archive status of this object put_python3_projects(id, project_id)Add a python docker to a project put_python3_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_python3_shares_users(id, user_ids, ...)Set the permissions users have on this object put_r(id, name, source, **kwargs)Replace all attributes of this R Script put_r_archive(id, status)Update the archive status of this object put_r_projects(id, project_id)Add a r docker to a project put_r_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_r_shares_users(id, user_ids, ...)Set the permissions users have on this object put_sql(id, name, sql, remote_host_id, ...)Replace all attributes of this SQL script put_sql_archive(id, status)Update the archive status of this object put_sql_projects(id, project_id)Add a scripts to a project put_sql_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_sql_shares_users(id, user_ids, ...)Set the permissions users have on this object -
delete_containers_projects(id, project_id)¶ Remove a container docker from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_containers_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the container.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_custom_projects(id, project_id)¶ Remove a Job from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_custom_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the custom.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_javascript_projects(id, project_id)¶ Remove a scripted sql from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_javascript_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the javascript.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_python3_projects(id, project_id)¶ Remove a python docker from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_python3_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the python.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_r_projects(id, project_id)¶ Remove a r docker from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_r_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the r.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
delete_sql_projects(id, project_id)¶ Remove a scripts from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
Returns: None
Response code 204: success
-
delete_sql_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the sql.
run_id : integer
The ID of the run.
Returns: None
Response code 202: success
Revoke the permissions a group has on this object
Parameters: id : integer
ID of the resource to be revoked
group_id : integer
ID of the group
Returns: None
Response code 204: success
Revoke the permissions a user has on this object
Parameters: id : integer
ID of the resource to be revoked
user_id : integer
ID of the user
Returns: None
Response code 204: success
-
get(id)¶ Get details about a script
Parameters: id : integer
The ID for the script.
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of script.
created_at : string/time
The time this script was created.
updated_at : string/time
The time this script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template this script uses, if any.
template_dependents_count : integer
How many other scripts use this one as a template.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
target_project_id : integer
Target project to which script outputs will be added.
archived : string
The archival status of the requested object(s).
sql : string
The raw SQL query for the script.
expanded_arguments : dict
Expanded arguments for use in injecting into different environments.
template_script_id : integer
The ID of the template script, if any.
-
get_containers(id)¶ View a container
Parameters: id : integer
The ID for the script.
Returns: id : integer
The ID for the script.
name : string
The name of the container.
type : string
The type of the script (e.g Container)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
template_dependents_count : integer
How many other scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template script.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
required_resources : dict:
- cpu : integer The number of CPU shares to allocate for the container. Each core has 1024 shares. - memory : integer The amount of RAM to allocate for the container (in MiB). - disk_space : number/float The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.
repo_http_uri : string
The location of a github repo to clone into the container, e.g. github.com/my-user/my-repo.git.
repo_ref : string
The tag or branch of the github repo to clone into the container.
remote_host_credential_id : integer
The id of the database credentials to pass into the environment of the container.
git_credential_id : integer
The id of the git credential to be used when checking out the specified git repo. If not supplied, the first git credential you’ve submitted will be used. Unnecessary if no git repo is specified or the git repo is public.
docker_command : string
The command to run on the container. Will be run via sh as: [“sh”, “-c”, dockerCommand]
docker_image_name : string
The name of the docker image to pull from DockerHub.
docker_image_tag : string
The tag of the docker image to pull from DockerHub (default: latest).
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
time_zone : string
The time zone of this script.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
target_project_id : integer
Target project to which script outputs will be added.
-
get_containers_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the container.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
container_id : integer
The ID of the container.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
get_custom(id)¶ Get a CustomScript
Parameters: id : integer
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g Custom)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
from_template_id : integer
The ID of the template script.
template_script_name : string
The name of the template script.
remote_host_id : integer
The remote host ID that this script will connect to.
credential_id : integer
The credential that this script will use.
code_preview : string
The code that this script will run with arguments inserted.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
archived : string
The archival status of the requested object(s).
target_project_id : integer
Target project to which script outputs will be added.
-
get_custom_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the custom.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
custom_id : integer
The ID of the custom.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
get_javascript(id)¶ Get a JavaScript Script
Parameters: id : integer
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g SQL, Container, Python, R, JavaScript)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template this script uses, if any.
template_dependents_count : integer
How many other scripts use this one as a template.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
target_project_id : integer
Target project to which script outputs will be added.
archived : string
The archival status of the requested object(s).
source : string
The body/text of the script.
remote_host_id : integer
The remote host ID that this script will connect to.
credential_id : integer
The credential that this script will use.
-
get_javascript_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the javascript.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
javascript_id : integer
The ID of the javascript.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
get_python3(id)¶ Get a Python Script
Parameters: id : integer
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g SQL, Container, Python, R, JavaScript)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template this script uses, if any.
template_dependents_count : integer
How many other scripts use this one as a template.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
target_project_id : integer
Target project to which script outputs will be added.
archived : string
The archival status of the requested object(s).
required_resources : dict:
- cpu : integer The number of CPU shares to allocate for the container. Each core has 1024 shares. Must be at least 2 shares. - memory : integer The amount of RAM to allocate for the container (in MiB). Must be at least 4 MiB. - disk_space : number/float The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.
source : string
The body/text of the script.
-
get_python3_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the python.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
python_id : integer
The ID of the python.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
get_r(id)¶ Get an R Script
Parameters: id : integer
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g SQL, Container, Python, R, JavaScript)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template this script uses, if any.
template_dependents_count : integer
How many other scripts use this one as a template.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
target_project_id : integer
Target project to which script outputs will be added.
archived : string
The archival status of the requested object(s).
required_resources : dict:
- cpu : integer The number of CPU shares to allocate for the container. Each core has 1024 shares. Must be at least 2 shares. - memory : integer The amount of RAM to allocate for the container (in MiB). Must be at least 4 MiB. - disk_space : number/float The amount of disk space, in GB, to allocate for the container. This space will be used to hold the git repo configured for the container and anything your container writes to /tmp or /data. Fractional values (e.g. 0.25) are supported.
source : string
The body/text of the script.
-
get_r_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the r.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
r_id : integer
The ID of the r.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
get_sql(id)¶ Get a SQL script
Parameters: id : integer
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g SQL, Container, Python, R, JavaScript)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
user_context : string
“runner” or “author”, who to execute the script as when run as a template.
params : list:
A definition of the parameters this script accepts in the arguments field. - name : string The variable's name as used within your code. - label : string The label to present to users when asking them for the value. - description : string A short sentence or fragment describing this parameter to the end user. - type : string The type of parameter. Valid options: string, integer, float, bool, file, database, credential_aws, credential_redshift, or credential_custom - required : boolean Whether this param is required. - value : string The value you would like to set this param to. Setting this value makes this parameter a fixed param. - default : string If an argument for this parameter is not defined, it will use this default value. Use true, True, t, y, yes, or 1 for true bool's or false, False, f, n, no, or 0 for false bool's. Cannot be used for parameters that are required or a credential type.
arguments : dict
Dictionary of name/value pairs to use to run this script. Only settable if this script has defined params.
is_template : boolean
Whether others scripts use this one as a template.
published_as_template_id : integer
The ID of the template that this script is backing.
from_template_id : integer
The ID of the template this script uses, if any.
template_dependents_count : integer
How many other scripts use this one as a template.
template_script_name : string
The name of the template script.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
schedule : dict:
- scheduled : boolean If the object is scheduled - scheduled_days : list Day based on numeric value starting at 0 for Sunday - scheduled_hours : list Hours of the day it is scheduled on - scheduled_minutes : list Minutes of the day it is scheduled on - scheduled_runs_per_hour : integer Alternative to scheduled minutes, number of times to run per hour
notifications : dict:
- urls : list URLs to receive a POST request at job completion - success_email_subject : string Custom subject line for success e-mail. - success_email_body : string Custom body text for success e-mail, written in Markdown. - success_email_addresses : list Addresses to notify by e-mail when the job completes successfully. - failure_email_addresses : list Addresses to notify by e-mail when the job fails. - stall_warning_minutes : integer Stall warning emails will be sent after this amount of minutes. - success_on : boolean If success email notifications are on - failure_on : boolean If failure email notifications are on
running_as : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
next_run_at : string/time
The time of the next scheduled run.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
hidden : boolean
The hidden status of the object. Setting this to true hides it from most API endpoints. The object can still be queried directly by ID
target_project_id : integer
Target project to which script outputs will be added.
archived : string
The archival status of the requested object(s).
sql : string
The raw SQL query for the script.
expanded_arguments : dict
Expanded arguments for use in injecting into different environments.
remote_host_id : integer
The remote host ID that this script will connect to.
credential_id : integer
The credential that this script will use.
code_preview : string
The code that this script will run with arguments inserted.
csv_settings : dict:
- include_header : boolean Whether or not to include headers in the output data. Default: true - compression : string The type of compression to use, if any, one of "none", "zip", or "gzip". Default: gzip - column_delimiter : string Which delimiter to use, one of "comma", "tab", or "pipe". Default: comma - unquoted : boolean Whether or not to quote fields. Default: false - force_multifile : boolean Whether or not the csv should be split into multiple files. Default: false - filename_prefix : string A user specified filename prefix for the output file to have. Default: null
-
get_sql_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the sql.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of this run.
sql_id : integer
The ID of this sql.
state : string
The state of this run.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started.
finished_at : string/time
The time that this run finished.
error : string
The error message for this run, if present.
output : list:
A list of the outputs of this script. - output_name : string The name of the output file. - file_id : integer The unique ID of the output file. - path : string The temporary link to download this output file, valid for 36 hours.
-
list(**kwargs)¶ List scripts
Parameters: type : string, optional
If specified, return objects of these types. The valid types are ‘sql’, ‘python3’, ‘r’, and ‘javascript’.
author : string, optional
If specified, return objects from this author. Must use user IDs. A comma separated list of IDs is also accepted to return objects from multiple authors.
status : string, optional
If specified, returns objects with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, 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_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g SQL, Container, Python, R, JavaScript)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
is_template : boolean
Whether others scripts use this one as a template.
from_template_id : integer
The ID of the template this script uses, if any.
links : dict:
- details : string The details link to get more information about the script. - runs : string The runs link to get the run information list for this script.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
template_script_id : integer
The ID of the template script, if any.
-
list_containers_projects(id)¶ List the projects a container docker belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
-
list_containers_runs(id, **kwargs)¶ List runs for the given container
Parameters: id : integer
The ID of the container.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the run.
container_id : integer
The ID of the container.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list_containers_runs_logs(id, run_id, **kwargs)¶ Get the logs for a run
Parameters: id : integer
The ID of the container.
run_id : integer
The ID of the run.
last_id : integer, optional
The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.
limit : integer, optional
The maximum number of log messages to return. Default of 10000.
Returns: id : integer
The ID of the log.
created_at : string/date-time
The time the log was created.
message : string
The log message.
level : string
The level of the log. One of unknown,fatal,error,warn,info,debug.
-
list_containers_runs_outputs(id, run_id, **kwargs)¶ List the outputs for a run
Parameters: id : integer
The ID of the output.
run_id : integer
The ID of the run.
limit : integer, optional
Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to created_at. Must be one of: created_at, id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: object_type : string
The type of the output. Valid values are File, Report, Table, or Project
object_id : integer
The ID of the output object.
name : string
The name of the output object.
link : string
The link to retrieve the output object.
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
list_custom(**kwargs)¶ List Custom Scripts
Parameters: from_template_id : integer, optional
The template script that this app uses.
author : string, optional
If specified, return objects from this author. Must use user IDs. A comma separated list of IDs is also accepted to return objects from multiple authors.
status : string, optional
If specified, returns objects with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.
archived : string, optional
The archival status of the requested object(s).
limit : integer, optional
Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to updated_at. Must be one of: updated_at, name, created_at.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to asc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID for the script.
name : string
The name of the script.
type : string
The type of the script (e.g Custom)
created_at : string/time
The time this script was created.
updated_at : string/time
The time the script was last updated.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
state : string
The status of the script’s last run.
finished_at : string/time
The time that the script’s last run finished.
projects : list:
A list of projects containing the script. - id : integer The ID for the project. - name : string The name of the project.
parent_id : integer
The ID of the parent job that will trigger this script
from_template_id : integer
The ID of the template script.
time_zone : string
The time zone of this script.
last_run : dict:
- id : integer - state : string - created_at : string/time The time that the run was queued. - started_at : string/time The time that the run started. - finished_at : string/time The time that the run completed. - error : string The error message for this run, if present.
archived : string
The archival status of the requested object(s).
-
list_custom_projects(id)¶ List the projects a Job belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
-
list_custom_runs(id, **kwargs)¶ List runs for the given custom
Parameters: id : integer
The ID of the custom.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the run.
custom_id : integer
The ID of the custom.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list_custom_runs_logs(id, run_id, **kwargs)¶ Get the logs for a run
Parameters: id : integer
The ID of the custom.
run_id : integer
The ID of the run.
last_id : integer, optional
The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.
limit : integer, optional
The maximum number of log messages to return. Default of 10000.
Returns: id : integer
The ID of the log.
created_at : string/date-time
The time the log was created.
message : string
The log message.
level : string
The level of the log. One of unknown,fatal,error,warn,info,debug.
-
list_custom_runs_outputs(id, run_id, **kwargs)¶ List the outputs for a run
Parameters: id : integer
The ID of the output.
run_id : integer
The ID of the run.
limit : integer, optional
Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to created_at. Must be one of: created_at, id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: object_type : string
The type of the output. Valid values are File, Report, Table, or Project
object_id : integer
The ID of the output object.
name : string
The name of the output object.
link : string
The link to retrieve the output object.
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
owners : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
total_user_shares : integer
For owners, the number of total users shared. For writers and readers, the number of visible users shared.
total_group_shares : integer
For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.
-
list_history(id)¶ Get the run history and outputs of this script
Parameters: id : integer
The ID for the script.
Returns: id : integer
The ID of this run.
sql_id : integer
The ID of this sql.
state : string
The state of this run.
is_cancel_requested : boolean
True if run cancel requested, else false.
finished_at : string/time
The time that this run finished.
error : string
The error message for this run, if present.
output : list:
A list of the outputs of this script. - output_name : string The name of the output file. - file_id : integer The unique ID of the output file. - path : string The temporary link to download this output file, valid for 36 hours.
-
list_javascript_projects(id)¶ List the projects a scripted sql belongs to
Parameters: id : integer
The ID of the resource.
Returns: id : integer
The ID for this project.
author : dict:
- id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
name : string
The name of this project.
description : string
A description of the project
users : list:
Users who can see the project - id : integer The ID of this user. - name : string This user's name. - username : string This user's username. - initials : string This user's initials. - online : boolean Whether this user is online.
auto_share : boolean
created_at : string/time
updated_at : string/time
archived : string
The archival status of the requested object(s).
-
list_javascript_runs(id, **kwargs)¶ List runs for the given javascript
Parameters: id : integer
The ID of the javascript.
limit : integer, optional
Number of results to return. Defaults to 20. Maximum allowed is 100.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to id. Must be one of: id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: id : integer
The ID of the run.
javascript_id : integer
The ID of the javascript.
state : string
The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.
is_cancel_requested : boolean
True if run cancel requested, else false.
started_at : string/time
The time the last run started at.
finished_at : string/time
The time the last run completed.
error : string
The error, if any, returned by the run.
-
list_javascript_runs_logs(id, run_id, **kwargs)¶ Get the logs for a run
Parameters: id : integer
The ID of the javascript.
run_id : integer
The ID of the run.
last_id : integer, optional
The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.
limit : integer, optional
The maximum number of log messages to return. Default of 10000.
Returns: id : integer
The ID of the log.
created_at : string/date-time
The time the log was created.
message : string
The log message.
level : string
The level of the log. One of unknown,fatal,error,warn,info,debug.
-
list_javascript_runs_outputs(id, run_id, **kwargs)¶ List the outputs for a run
Parameters: id : integer
The ID of the output.
run_id : integer
The ID of the run.
limit : integer, optional
Number of results to return. Defaults to its maximum of 50.
page_num : integer, optional
Page number of the results to return. Defaults to the first page, 1.
order : string, optional
The field on which to order the result set. Defaults to created_at. Must be one of: created_at, id.
order_dir : string, optional
Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.
iterator : bool, optional
If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.
Returns: object_type : string
The type of the output. Valid values are File, Report, Table, or Project
object_id : integer
The ID of the output object.
name : string
The name of the output object.
link : string
The link to retrieve the output object.
List users and groups permissioned on this object
Parameters: id : integer
The ID of the object.
Returns: readers : dict:
- users : list:: - id : integer - name : string - groups : list:: - id : integer - name : string
writers : dict:
- users : list:: - id
-