API Resources¶
Announcements¶
-
class
Announcements(session_kwargs, return_type='civis')¶ Methods
list(*[, limit, page_num, order, order_dir, ...])List announcements -
list(*, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List announcements
Parameters: limit : integer, optional
Number of results to return. Defaults to 10. 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 released_at. Must be one of: released_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 announcement
subject : string
The subject of this announcement.
body : string
The body of this announcement.
released_at : string/date-time
The date and time this announcement was released.
created_at : string/date-time
updated_at : string/date-time
-
Apps¶
-
class
Apps(session_kwargs, return_type='civis')¶ Methods
delete_instances_projects(id, project_id, slug)Remove a AppInstance from a project delete_instances_shares_groups(id, group_id, ...)Revoke the permissions a group has on this object delete_instances_shares_users(id, user_id, slug)Revoke the permissions a user has on this object get(slug)List details of a Decision Application get_instances(id, slug)Return a given app instance list()List apps list_instances(slug, *[, archived, ...])List the instances of a Decision Application list_instances_projects(id, slug, *[, hidden])List the projects a AppInstance belongs to list_instances_shares(id, slug)List users and groups permissioned on this object patch_instances(id, slug, *[, name])Update a given app instance post_instances(slug, *[, name])Create a new instance of an application of the given slug put_instances_archive(id, slug, status)Update the archive status of this object put_instances_projects(id, project_id, slug)Add a AppInstance to a project put_instances_shares_groups(id, slug, ...[, ...])Set the permissions groups has on this object put_instances_shares_users(id, slug, ...[, ...])Set the permissions users have on this object -
delete_instances_projects(id, project_id, slug)¶ Remove a AppInstance from a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
slug : string
The slug for the application.
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
slug : string
The slug for the application.
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
slug : string
The slug for the application.
Returns: None
Response code 204: success
-
get(slug)¶ List details of a Decision Application
Parameters: slug : string
The slug for the application.
Returns: slug : string
The slug for the application.
id : integer
The unique id of the application.
instance_name : string
A word that describes an instance of this app.
name : string
The name of the application.
current_release : dict:
- id : integer The unique id of the release. - app_id : integer The id of the app the release belongs to. - report_template_id : integer ID of the report template for this release. - resources : dict A hash of resources associated with this release.
features : dict
App features.
-
get_instances(id, slug)¶ Return a given app instance
Parameters: id : integer
The unique id of the instance.
slug : string
The slug for the application.
Returns: id : integer
The unique id of the instance.
name : string
The name of the instance.
app_release_id : integer
The id of the app release the instance belongs to.
report_id : integer
The id of the report the instance belongs to.
created_at : string/time
The time the instance was created at.
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.
project_id : integer
The id of the project collecting all the objects that belong to this app instance.
auth_code_url : string
api_key : string
A Civis API key that can be used by this app instance.
-
list()¶ List apps
Returns: slug : string
The slug for the application.
id : integer
The unique id of the application.
instance_name : string
A word that describes an instance of this app.
name : string
The name of the application.
-
list_instances(slug, *, archived='DEFAULT', app_release_id='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List the instances of a Decision Application
Parameters: slug : string
The slug for the application.
archived : string, optional
The archival status of the requested object(s).
app_release_id : integer, optional
If supplied, return only instances matching this release.
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 id. Must be one of: id, 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 unique id of the instance.
name : string
The name of the instance.
app_release_id : integer
The id of the app release the instance belongs to.
report_id : integer
The id of the report the instance belongs to.
created_at : string/time
The time the instance was created at.
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.
project_id : integer
The id of the project collecting all the objects that belong to this app instance.
-
list_instances_projects(id, slug, *, hidden='DEFAULT')¶ List the projects a AppInstance belongs to
Parameters: id : integer
The ID of the resource.
slug : string
The slug for the application.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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.
slug : string
The slug for the application.
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.
-
patch_instances(id, slug, *, name='DEFAULT')¶ Update a given app instance
Parameters: id : integer
The unique id of the instance.
slug : string
The slug for the application.
name : string, optional
The name of the instance.
Returns: id : integer
The unique id of the instance.
name : string
The name of the instance.
app_release_id : integer
The id of the app release the instance belongs to.
report_id : integer
The id of the report the instance belongs to.
created_at : string/time
The time the instance was created at.
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.
project_id : integer
The id of the project collecting all the objects that belong to this app instance.
auth_code_url : string
api_key : string
A Civis API key that can be used by this app instance.
-
post_instances(slug, *, name='DEFAULT')¶ Create a new instance of an application of the given slug
Parameters: slug : string
The slug for the application.
name : string, optional
The name of the instance.
Returns: id : integer
The unique id of the instance.
name : string
The name of the instance.
app_release_id : integer
The id of the app release the instance belongs to.
report_id : integer
The id of the report the instance belongs to.
created_at : string/time
The time the instance was created at.
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.
project_id : integer
The id of the project collecting all the objects that belong to this app instance.
auth_code_url : string
api_key : string
A Civis API key that can be used by this app instance.
-
put_instances_archive(id, slug, status)¶ Update the archive status of this object
Parameters: id : integer
The ID of the object.
slug : string
The slug for the application.
status : boolean
The desired archived status of the object.
Returns: id : integer
The unique id of the instance.
name : string
The name of the instance.
app_release_id : integer
The id of the app release the instance belongs to.
report_id : integer
The id of the report the instance belongs to.
created_at : string/time
The time the instance was created at.
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.
project_id : integer
The id of the project collecting all the objects that belong to this app instance.
auth_code_url : string
api_key : string
A Civis API key that can be used by this app instance.
-
put_instances_projects(id, project_id, slug)¶ Add a AppInstance to a project
Parameters: id : integer
ID of the resource
project_id : integer
The ID of the project
slug : string
The slug for the application.
Returns: None
Response code 204: success
Set the permissions groups has on this object
Parameters: id : integer
ID of the resource to be shared
slug : string
The slug for the application.
group_ids : list
An array of one or more group IDs
permission_level : string
Options are: “read”, “write”, or “manage”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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
slug : string
The slug for the application.
user_ids : list
An array of one or more user IDs
permission_level : string
Options are: “read”, “write”, or “manage”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
-
Clusters¶
-
class
Clusters(session_kwargs, return_type='civis')¶ Methods
get_kubernetes(id)Describe a Kubernetes Cluster get_workers(id)Describe a Worker Cluster list_kubernetes(*[, organization_slug, ...])List Kubernetes Clusters list_workers(*[, limit, page_num, order, ...])List Worker Clusters list_workers_active_jobs(id)List Active Jobs for a Worker Cluster list_workers_queued_jobs(id)List Queued Jobs for a Worker Cluster -
get_kubernetes(id)¶ Describe a Kubernetes Cluster
Parameters: id : integer
The ID of this cluster.
Returns: id : integer
The ID of this cluster.
instance_type : string
The EC2 instance types in this cluster.
min_instances : integer
The minimum number of instances in this cluster.
max_instances : integer
The maximum number of instances in this cluster.
instance_max_memory : integer
The amount of memory available to a single instance.
instance_max_cpu : integer
The number of processor shares available to a single instance.
organization_id : string
The id of this cluster’s organization.
organization_slug : string
The slug of this cluster’s organization.
security_group_id : string
The security group to be added to the nodes of this cluster
-
get_workers(id)¶ Describe a Worker Cluster
Parameters: id : integer
The ID of this cluster.
Returns: id : integer
The ID of this cluster.
instance_type : string
The EC2 instance types in this cluster.
min_instances : integer
The minimum number of instances in this cluster.
max_instances : integer
The maximum number of instances in this cluster.
instances : integer
The number of instances currently in this cluster.
instance_max_memory : integer
The amount of memory available to a single instance.
instance_max_cpu : integer
The number of processor shares available to a single instance.
instance_max_disk_space : number/float
The amount of memory available to a single instance.
region : string
The AWS region that this cluster is in.
active_jobs_count : integer
The number of jobs currently being run in the cluster.
queued_jobs_count : integer
The number of jobs currently waiting to be run on the cluster.
-
list_kubernetes(*, organization_slug='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List Kubernetes Clusters
Parameters: organization_slug : string, optional
The slug of this cluster’s organization.
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 organization_id. Must be one of: organization_id, 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 of this cluster.
instance_type : string
The EC2 instance types in this cluster.
min_instances : integer
The minimum number of instances in this cluster.
max_instances : integer
The maximum number of instances in this cluster.
instance_max_memory : integer
The amount of memory available to a single instance.
instance_max_cpu : integer
The number of processor shares available to a single instance.
organization_id : string
The id of this cluster’s organization.
organization_slug : string
The slug of this cluster’s organization.
security_group_id : string
The security group to be added to the nodes of this cluster
-
list_workers(*, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List Worker Clusters
Parameters: 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 id. Must be one of: id, 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 of this cluster.
instance_type : string
The EC2 instance types in this cluster.
min_instances : integer
The minimum number of instances in this cluster.
max_instances : integer
The maximum number of instances in this cluster.
region : string
The AWS region that this cluster is in.
active_jobs_count : integer
The number of jobs currently being run in the cluster.
queued_jobs_count : integer
The number of jobs currently waiting to be run on the cluster.
-
list_workers_active_jobs(id)¶ List Active Jobs for a Worker Cluster
Parameters: id : integer
The ID of this cluster.
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.
required_cpu : integer
The CPU shares required by the script.
required_disk_space : integer
The disk space in GB required by the script.
required_memory : integer
The memory in MB required by the script.
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.
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.
-
list_workers_queued_jobs(id)¶ List Queued Jobs for a Worker Cluster
Parameters: id : integer
The ID of this cluster.
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.
required_cpu : integer
The CPU shares required by the script.
required_disk_space : integer
The disk space in GB required by the script.
required_memory : integer
The memory in MB required by the script.
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.
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.
-
Codes¶
-
class
Codes(session_kwargs, return_type='civis')¶ Methods
delete(id)Delete a code get(id)Show basic code info list(*[, limit, type, featured])List codes patch(id, *[, name, type, body, readme, ...])Update a code post(name, type, body, readme, *[, score, ...])Create a new code put(id, name, type, body, readme, *[, ...])Update a code -
delete(id)¶ Delete a code
Parameters: id : integer
The ID for this code.
Returns: None
Response code 204: success
-
get(id)¶ Show basic code info
Parameters: id : integer
The ID for this code.
Returns: id : integer
The ID for this code.
name : string
Name of code.
type : string
The code’s type; e.g., Code::FrontEnd.
body : string
Actual code contents; e.g., HTML, SQL, etc.
readme : string
User specified information about this code. Markdown format accepted.
score : integer
Internal Civis Use Only.
auth_s3_url : string
Authorized_s3_link to file.
created_at : string/time
The creation time for this code.
updated_at : string/time
The last modification time for this code.
-
list(*, limit='DEFAULT', type='DEFAULT', featured='DEFAULT')¶ List codes
Parameters: limit : integer, optional
The maximum number of codes to return.
type : string, optional
The code’s type; e.g., Code::FrontEnd.
featured : boolean, optional
If true, return featured codes.
Returns: id : integer
The ID for this code.
name : string
Name of code.
type : string
The code’s type; e.g., Code::FrontEnd.
created_at : string/time
The creation time for this code.
updated_at : string/time
The last modification time for this code.
-
patch(id, *, name='DEFAULT', type='DEFAULT', body='DEFAULT', readme='DEFAULT', score='DEFAULT', auth_s3_url='DEFAULT')¶ Update a code
Parameters: id : integer
The ID for this code.
name : string, optional
Name of code.
type : string, optional
The code’s type; e.g., Code::FrontEnd.
body : string, optional
Actual code contents; e.g., HTML, SQL, etc.
readme : string, optional
User specified information about this code. Markdown format accepted.
score : integer, optional
Internal Civis Use Only.
auth_s3_url : string, optional
Authorized_s3_link to file.
Returns: None
Response code 204: success
-
post(name, type, body, readme, *, score='DEFAULT', auth_s3_url='DEFAULT')¶ Create a new code
Parameters: name : string
Name of code.
type : string
The code’s type; e.g., Code::FrontEnd.
body : string
Actual code contents; e.g., HTML, SQL, etc.
readme : string
User specified information about this code. Markdown format accepted.
score : integer, optional
Internal Civis Use Only.
auth_s3_url : string, optional
Authorized_s3_link to file.
Returns: None
Response code 204: success
-
put(id, name, type, body, readme, *, score='DEFAULT', auth_s3_url='DEFAULT')¶ Update a code
Parameters: id : integer
The ID for this code.
name : string
Name of code.
type : string
The code’s type; e.g., Code::FrontEnd.
body : string
Actual code contents; e.g., HTML, SQL, etc.
readme : string
User specified information about this code. Markdown format accepted.
score : integer, optional
Internal Civis Use Only.
auth_s3_url : string, optional
Authorized_s3_link to file.
Returns: id : integer
The ID for this code.
name : string
Name of code.
type : string
The code’s type; e.g., Code::FrontEnd.
body : string
Actual code contents; e.g., HTML, SQL, etc.
readme : string
User specified information about this code. Markdown format accepted.
score : integer
Internal Civis Use Only.
auth_s3_url : string
Authorized_s3_link to file.
created_at : string/time
The creation time for this code.
updated_at : string/time
The last modification time for this code.
-
Credentials¶
-
class
Credentials(session_kwargs, 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(id)Get a credential list(*[, type, default, limit, page_num, ...])List credentials list_shares(id)List users and groups permissioned on this object post(type, username, password, *[, name, ...])Create a credential post_authenticate(url, remote_host_type, ...)Authenticate against a remote host post_temporary(id, *[, duration])Generate a temporary credential for accessing S3 put(id, type, username, password, *[, name, ...])Update an existing credential put_shares_groups(id, group_ids, ...[, ...])Set the permissions groups has on this object put_shares_users(id, user_ids, ...[, ...])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(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(*, type='DEFAULT', default='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ 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.
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(type, username, password, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', system_credential='DEFAULT')¶ Create 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.
system_credential : boolean, optional
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, *, duration='DEFAULT')¶ 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, *, name='DEFAULT', description='DEFAULT', remote_host_id='DEFAULT', system_credential='DEFAULT')¶ 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.
system_credential : boolean, optional
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.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
Databases¶
-
class
Databases(session_kwargs, 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.
-
Endpoints¶
Enhancements¶
-
class
Enhancements(session_kwargs, return_type='civis')¶ Methods
delete_cass_ncoa_projects(id, project_id)Remove a JobTypes::CassNcoa from a project delete_cass_ncoa_runs(id, run_id)Cancel a run delete_cass_ncoa_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_cass_ncoa_shares_users(id, user_id)Revoke the permissions a user has on this object get_cass_ncoa(id)Get a CASS/NCOA Enhancement get_cass_ncoa_runs(id, run_id)Check status of a run list(*[, type, author, status, archived, ...])List Enhancements list_cass_ncoa_projects(id, *[, hidden])List the projects a JobTypes::CassNcoa belongs to list_cass_ncoa_runs(id, *[, limit, ...])List runs for the given cass_ncoa list_cass_ncoa_runs_logs(id, run_id, *[, ...])Get the logs for a run list_cass_ncoa_runs_outputs(id, run_id, *[, ...])List the outputs for a run list_cass_ncoa_shares(id)List users and groups permissioned on this object list_types()List available enhancement types patch_cass_ncoa(id, *[, name, schedule, ...])Update some attributes of this CASS/NCOA Enhancement post_cass_ncoa(name, source, *[, schedule, ...])Create a CASS/NCOA Enhancement post_cass_ncoa_cancel(id)Cancel a run post_cass_ncoa_runs(id)Start a run put_cass_ncoa(id, name, source, *[, ...])Replace all attributes of this CASS/NCOA Enhancement put_cass_ncoa_archive(id, status)Update the archive status of this object put_cass_ncoa_projects(id, project_id)Add a JobTypes::CassNcoa to a project put_cass_ncoa_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_cass_ncoa_shares_users(id, user_ids, ...)Set the permissions users have on this object -
delete_cass_ncoa_projects(id, project_id)¶ Remove a JobTypes::CassNcoa 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_cass_ncoa_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the cass_ncoa.
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_cass_ncoa(id)¶ Get a CASS/NCOA Enhancement
Parameters: id : integer
Returns: id : integer
The ID for the enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string
The limiting sql.
archived : string
The archival status of the requested object(s).
-
get_cass_ncoa_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the cass_ncoa.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
cass_ncoa_id : integer
The ID of the cass_ncoa.
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(*, type='DEFAULT', author='DEFAULT', status='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List Enhancements
Parameters: type : string, optional
If specified, return objects of these types.
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 enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
archived : string
The archival status of the requested object(s).
-
list_cass_ncoa_projects(id, *, hidden='DEFAULT')¶ List the projects a JobTypes::CassNcoa belongs to
Parameters: id : integer
The ID of the resource.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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_cass_ncoa_runs(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List runs for the given cass_ncoa
Parameters: id : integer
The ID of the cass_ncoa.
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.
cass_ncoa_id : integer
The ID of the cass_ncoa.
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_cass_ncoa_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶ Get the logs for a run
Parameters: id : integer
The ID of the cass_ncoa.
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_cass_ncoa_runs_outputs(id, run_id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List the outputs for a run
Parameters: id : integer
The ID of the job.
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, Table, Report, Project, or Credential
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_types()¶ List available enhancement types
Returns: name : string
The name of the type.
-
patch_cass_ncoa(id, *, name='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', source='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')¶ Update some attributes of this CASS/NCOA Enhancement
Parameters: id : integer
The ID for the enhancement.
name : string, optional
The name of the enhancement.
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict, optional:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict, optional:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict, optional:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean, optional
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean, optional
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer, optional
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string, optional
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string, optional
The limiting sql.
Returns: id : integer
The ID for the enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string
The limiting sql.
archived : string
The archival status of the requested object(s).
-
post_cass_ncoa(name, source, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')¶ Create a CASS/NCOA Enhancement
Parameters: name : string
The name of the enhancement.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
destination : dict, optional:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict, optional:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean, optional
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean, optional
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer, optional
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string, optional
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string, optional
The limiting sql.
Returns: id : integer
The ID for the enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string
The limiting sql.
archived : string
The archival status of the requested object(s).
-
post_cass_ncoa_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_cass_ncoa_runs(id)¶ Start a run
Parameters: id : integer
The ID of the cass_ncoa.
Returns: id : integer
The ID of the run.
cass_ncoa_id : integer
The ID of the cass_ncoa.
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_cass_ncoa(id, name, source, *, schedule='DEFAULT', parent_id='DEFAULT', notifications='DEFAULT', destination='DEFAULT', column_mapping='DEFAULT', use_default_column_mapping='DEFAULT', perform_ncoa='DEFAULT', ncoa_credential_id='DEFAULT', output_level='DEFAULT', limiting_sql='DEFAULT')¶ Replace all attributes of this CASS/NCOA Enhancement
Parameters: id : integer
The ID for the enhancement.
name : string
The name of the enhancement.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
destination : dict, optional:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict, optional:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean, optional
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean, optional
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer, optional
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string, optional
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string, optional
The limiting sql.
Returns: id : integer
The ID for the enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string
The limiting sql.
archived : string
The archival status of the requested object(s).
-
put_cass_ncoa_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 the enhancement.
name : string
The name of the enhancement.
type : string
The type of the enhancement (e.g CASS-NCOA)
created_at : string/time
The time this enhancement was created.
updated_at : string/time
The time the enhancement 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 enhancement’s last run
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
Parent ID that triggers this enhancement.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
source : dict:
- database_table : dict:: - schema : string The schema name of the source table. - table : string The name of the source table. - remote_host_id : integer The ID of the database host for the table. - credential_id : integer The id of the credentials to be used when performing the enhancement. - multipart_key : list The source table primary key.
destination : dict:
- database_table : dict:: - schema : string The schema name for the output data. - table : string The table name for the output data.
column_mapping : dict:
- address1 : string The first address line. - address2 : string The second address line. - city : string The city of an address. - state : string The state of an address. - zip : string The zip code of an address. - name : string The full name of the resident at this address. If needed, separate multiple columns with `+`, e.g. `first_name+last_name` - company : string The name of the company located at this address.use_default_column_mapping : boolean
Defaults to true, where the existing column mapping on the input table will be used. If false, a custom column mapping must be provided.
perform_ncoa : boolean
Whether to update addresses for records matching the National Change of Address (NCOA) database.
ncoa_credential_id : integer
Credential to use when performing NCOA updates. Required if ‘performNcoa’ is true.
output_level : string
The set of fields persisted by a CASS or NCOA enhancement.For CASS enhancements, one of ‘cass’ or ‘all.’For NCOA enhancements, one of ‘cass’, ‘ncoa’ , ‘coalesced’ or ‘all’.By default, all fields will be returned.
limiting_sql : string
The limiting sql.
archived : string
The archival status of the requested object(s).
-
put_cass_ncoa_projects(id, project_id)¶ Add a JobTypes::CassNcoa 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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
-
Exports¶
-
class
Exports(session_kwargs, return_type='civis')¶ Methods
list(*[, type, author, status, hidden, ...])List -
list(*, type='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List
Parameters: type : string, optional
If specified, return exports of these types. It accepts a comma-separated list, possible values are ‘database’ and ‘gdoc’.
author : string, optional
If specified, return exports from this author. It accepts a comma-separated list of author ids.
status : string, optional
If specified, returns export with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘failed’, ‘succeeded’, ‘idle’, ‘scheduled’.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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 this export.
name : string
The name of this export.
type : string
The type of export.
created_at : string/time
The creation time for this export.
updated_at : string/time
The last modification time for this export.
state : string
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.
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.
-
Files¶
-
class
Files(session_kwargs, 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, *[, link_expires_at])Get details about a file list_projects(id, *[, hidden])List the projects a Data::S3File belongs to list_shares(id)List users and groups permissioned on this object post(name, *[, expires_at])Initiate an upload of a file into the platform post_multipart(name, num_parts, *[, expires_at])Initiate a multipart upload post_multipart_complete(id)Complete a multipart upload 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, ...[, ...])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, *, link_expires_at='DEFAULT')¶ Get details about a file
Parameters: id : integer
The ID of the file object.
link_expires_at : string, optional
The date and time the download link will expire. Must be a time between now and 36 hours from now. Defaults to 30 minutes from now.
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, *, hidden='DEFAULT')¶ List the projects a Data::S3File belongs to
Parameters: id : integer
The ID of the resource.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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, *, expires_at='DEFAULT')¶ 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.
-
post_multipart(name, num_parts, *, expires_at='DEFAULT')¶ Initiate a multipart upload
Parameters: name : string
The file name.
num_parts : integer
The number of parts in which the file will be uploaded. This parameter determines the number of presigned URLs that are returned.
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_urls : list
An array of URLs that may be used to upload file parts. Use separate PUT requests to complete the part uploads. Links expire after 12 hours.
-
post_multipart_complete(id)¶ Complete a multipart upload
Parameters: id : integer
The ID of the file object.
Returns: None
Response code 204: success
-
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
-
Groups¶
-
class
Groups(session_kwargs, return_type='civis')¶ Methods
list(*[, query, permission, limit, ...])List Groups -
list(*, query='DEFAULT', permission='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List Groups
Parameters: query : string, optional
If specified, it will filter the groups returned. Prefix matching is supported (e.g., “query=group” will return “group” and “group of people”, but not “my group”.
permission : string, optional
A permissions string, one of “read”, “write”, or “manage”. Lists only groups for which the current user has that permission.
limit : integer, optional
Number of results to return. Defaults to 50. 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 name. Must be one of: 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 of this group.
name : string
This group’s name.
created_at : string/time
The date and time when this group was created.
slug : string
The slug for this group.
organization_id : integer
The organization associated with this group.
-
Imports¶
-
class
Imports(session_kwargs, 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 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(*[, type, author, destination, status, ...])List list_batches(*[, hidden, limit, page_num, ...])List batch imports list_files_runs(id, *[, limit, page_num, ...])List runs for the given import list_files_runs_logs(id, run_id, *[, ...])Get the logs for a run list_projects(id, *[, hidden])List the projects a JobTypes::Import belongs to list_runs(id)Get the run history of this import list_runs_logs(id, run_id, *[, last_id, limit])Get the logs for a run list_shares(id)List users and groups permissioned on this object post(name, sync_type, is_outbound, *[, ...])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, *[, ...])Create a sync put(id, name, sync_type, is_outbound, *[, ...])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, ...[, ...])Set the permissions users have on this object put_syncs(id, sync_id, source, destination, *)Update a sync put_syncs_archive(id, sync_id, *[, status])Update the archive status of this 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
-
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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
job_type : string
The job type of this import.
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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id. - destination : dict:: - path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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.
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.
-
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(*, type='DEFAULT', author='DEFAULT', destination='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List
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’.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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
job_type : string
The job type of this import.
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(*, hidden='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List batch imports
Parameters: hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ 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_files_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶ Get the logs for a run
Parameters: id : integer
The ID of the import.
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_projects(id, *, hidden='DEFAULT')¶ List the projects a JobTypes::Import belongs to
Parameters: id : integer
The ID of the resource.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶ Get the logs for a run
Parameters: id : integer
The ID of the import.
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 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, *, source='DEFAULT', destination='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', parent_id='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT')¶ 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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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
job_type : string
The job type of this import.
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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id. - destination : dict:: - path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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.
archived : string
The archival status of the requested object(s).
-
post_batches(file_ids, schema, table, remote_host_id, credential_id, *, column_delimiter='DEFAULT', first_row_is_header='DEFAULT', compression='DEFAULT', hidden='DEFAULT')¶ 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.
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.
-
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, *, max_errors='DEFAULT', existing_table_rows='DEFAULT', distkey='DEFAULT', sortkey1='DEFAULT', sortkey2='DEFAULT', column_delimiter='DEFAULT', first_row_is_header='DEFAULT', multipart='DEFAULT', hidden='DEFAULT')¶ 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.
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, *, advanced_options='DEFAULT')¶ Create a sync
Parameters: id : integer
source : dict:
- path : string The path of the dataset to sync from; for a database source, schema.tablename. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id.
destination : dict:
- path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name.
advanced_options : dict, optional:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id.
destination : dict:
- path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name.
advanced_options : dict:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - contact_lists : string - soql_query : string
-
put(id, name, sync_type, is_outbound, *, source='DEFAULT', destination='DEFAULT', schedule='DEFAULT', notifications='DEFAULT', parent_id='DEFAULT', next_run_at='DEFAULT', time_zone='DEFAULT')¶ 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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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
job_type : string
The job type of this import.
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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id. - destination : dict:: - path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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
job_type : string
The job type of this import.
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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id. - destination : dict:: - path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - advanced_options : dict:: - max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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, *, advanced_options='DEFAULT')¶ 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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id.
destination : dict:
- path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name.
advanced_options : dict, optional:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - 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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id.
destination : dict:
- path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name.
advanced_options : dict:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - contact_lists : string - soql_query : string
-
put_syncs_archive(id, sync_id, *, status='DEFAULT')¶ Update the archive status of this sync
Parameters: id : integer
The ID of the import to fetch.
sync_id : integer
The ID of the sync to fetch.
status : boolean, optional
The desired archived status of the sync.
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. If you are doing a Google Sheet export, this can be blank. This is a legacy parameter, it is recommended you use one of the following: databaseTable, file, googleWorksheet, salesforce, silverpop - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - file : dict:: - id : integer The file id. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name. - salesforce : dict:: - object_name : string The Salesforce object name. - silverpop : dict:: - list_id : integer The Silverpop list id.
destination : dict:
- path : string The schema.tablename to sync to. If you are doing a Google Sheet export, this is the spreadsheet and sheet name separated by a period. i.e. if you have a spreadsheet named "MySpreadsheet" and a sheet called "Sheet1" this field would be "MySpreadsheet.Sheet1". This is a legacy parameter, it is recommended you use one of the following: databaseTable, googleWorksheet - database_table : dict:: - schema : string The database schema name. - table : string The database table name. - google_worksheet : dict:: - spreadsheet : string The spreadsheet document name. - worksheet : string The worksheet tab name.
advanced_options : dict:
- max_errors : integer - existing_table_rows : string - distkey : string - sortkey1 : string - sortkey2 : string - column_delimiter : string - column_overrides : dict Hash used for overriding auto-detected names and types, with keys being the current name of the column being overridden. - 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 - chunking_method : string The method used to break the data into smaller chunks for transfer. The value can be set to sorted_by_identity_columns or if not set the chunking method will be choosen automatically. - first_row_is_header : boolean - export_action : string The kind of export action you want to have the export execute. Set to "newsprsht" if you want a new worksheet inside a new spreadsheet. Set to "newwksht" if you want a new worksheet inside an existing spreadsheet. Set to "updatewksht" if you want to overwrite an existing worksheet inside an existing spreadsheet. Set to "appendwksht" if you want to append to the end of an existing worksheet inside an existing spreadsheet. - sql_query : string If you are doing a Google Sheet export, this is your SQL query. - contact_lists : string - soql_query : string
-
Jobs¶
-
class
Jobs(session_kwargs, 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(*[, state, type, q, permission, ...])List 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, *[, hidden])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, ...[, ...])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.
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(*, state='DEFAULT', type='DEFAULT', q='DEFAULT', permission='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List
Parameters: 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.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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.
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
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.
archived : string
The archival status of the requested object(s).
-
list_projects(id, *, hidden='DEFAULT')¶ List the projects a Job belongs to
Parameters: id : integer
The ID of the resource.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
-
Media¶
-
class
Media(session_kwargs, return_type='civis')¶ Methods
delete_optimizations_runs(id, run_id)Cancel a run delete_optimizations_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_optimizations_shares_users(id, user_id)Revoke the permissions a user has on this object delete_spot_orders_shares_groups(id, group_id)Revoke the permissions a group has on this object delete_spot_orders_shares_users(id, user_id)Revoke the permissions a user has on this object get_optimizations(id)Show a single optimization get_optimizations_runs(id, run_id)Check status of a run get_spot_orders(id)Show a single spot order list_dmas(*[, name, number])List all Designated Market Areas list_optimizations(*[, archived, limit, ...])List all optimizations list_optimizations_runs(id, *[, limit, ...])List runs for the given optimization list_optimizations_runs_logs(id, run_id, *)Get the logs for a run list_optimizations_shares(id)List users and groups permissioned on this object list_ratecards(*[, filename, dma_number])List all ratecards list_spot_orders(*[, id, archived])List all spot orders list_spot_orders_shares(id)List users and groups permissioned on this object list_targets(*[, name, identifier, data_source])List all Media Targets patch_optimizations(id, *[, name, runs])Edit an existing optimization post_optimizations(runs, *[, name])Create a new optimization post_optimizations_clone(id)Clone an existing optimization post_optimizations_runs(id)Start a run post_spot_orders(*[, body])Create a spot order put_optimizations_archive(id, status)Update the archive status of this object put_optimizations_shares_groups(id, ...[, ...])Set the permissions groups has on this object put_optimizations_shares_users(id, user_ids, ...)Set the permissions users have on this object put_spot_orders(id, *[, body])Edit the specified spot order put_spot_orders_archive(id, status)Update the archive status of this object put_spot_orders_shares_groups(id, group_ids, ...)Set the permissions groups has on this object put_spot_orders_shares_users(id, user_ids, ...)Set the permissions users have on this object -
delete_optimizations_runs(id, run_id)¶ Cancel a run
Parameters: id : integer
The ID of the optimization.
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
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_optimizations(id)¶ Show a single optimization
Parameters: id : integer
The optimization ID.
Returns: id : integer
The optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
report_link : string
A link to the visual report for the optimization.
spot_order_link : string
A link to the json version of the spot order.
file_links : list
Links to the csv and xml versions of the spot order.
runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
-
get_optimizations_runs(id, run_id)¶ Check status of a run
Parameters: id : integer
The ID of the optimization.
run_id : integer
The ID of the run.
Returns: id : integer
The ID of the run.
optimization_id : integer
The ID of the optimization.
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_spot_orders(id)¶ Show a single spot order
Parameters: id : integer
The ID for the spot order.
Returns: id : integer
The ID for the spot order.
archived : string
The archival status of the requested object(s).
csv_s3_uri : string
S3 URI for the spot order CSV file.
json_s3_uri : string
S3 URI for the spot order JSON file.
xml_archive_s3_uri : string
S3 URI for the spot order XML archive.
last_transform_job_id : integer
ID of the spot order transformation job.
-
list_dmas(*, name='DEFAULT', number='DEFAULT')¶ List all Designated Market Areas
Parameters: name : string, optional
If specified, will be used to filter the DMAs returned. Substring matching is supported with “%” and “*” wildcards (e.g., “name=%region%” will return both “region1” and “my region”).
number : integer, optional
If specified, will be used to filter the DMAS by number.
Returns: name : string
Name for the DMA region.
number : integer
Identifier number for a DMA.
-
list_optimizations(*, archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List all optimizations
Parameters: 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 created_at. Must be one of: created_at, author, 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 optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
-
list_optimizations_runs(id, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List runs for the given optimization
Parameters: id : integer
The ID of the optimization.
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.
optimization_id : integer
The ID of the optimization.
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_optimizations_runs_logs(id, run_id, *, last_id='DEFAULT', limit='DEFAULT')¶ Get the logs for a run
Parameters: id : integer
The ID of the optimization.
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 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_ratecards(*, filename='DEFAULT', dma_number='DEFAULT')¶ List all ratecards
Parameters: filename : string, optional
If specified, will be used to filter the ratecards returned. Substring matching is supported with “%” and “*” wildcards (e.g., “filename=%ratecard%” will return both “ratecard 1” and “my ratecard”).
dma_number : integer, optional
If specified, will be used to filter the ratecards by DMA.
Returns: id : integer
The ratecard ID.
filename : string
Name of the ratecard file.
start_on : string/date
First day to which the ratecard applies.
end_on : string/date
Last day to which the ratecard applies.
dma_number : integer
Number of the DMA associated with the ratecard.
-
list_spot_orders(*, id='DEFAULT', archived='DEFAULT')¶ List all spot orders
Parameters: id : integer, optional
The ID for the spot order.
archived : string, optional
The archival status of the requested object(s).
Returns: id : integer
The ID for the spot order.
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_targets(*, name='DEFAULT', identifier='DEFAULT', data_source='DEFAULT')¶ List all Media Targets
Parameters: name : string, optional
The name of the target.
identifier : string, optional
A unique identifier for this target.
data_source : string, optional
The source of viewership data for this target.
Returns: name : string
The name of the target.
identifier : string
A unique identifier for this target.
data_source : string
The source of viewership data for this target.
-
patch_optimizations(id, *, name='DEFAULT', runs='DEFAULT')¶ Edit an existing optimization
Parameters: id : integer
The optimization ID.
name : string, optional
The name of the optimization.
runs : list, optional:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
Returns: id : integer
The optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
report_link : string
A link to the visual report for the optimization.
spot_order_link : string
A link to the json version of the spot order.
file_links : list
Links to the csv and xml versions of the spot order.
runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
-
post_optimizations(runs, *, name='DEFAULT')¶ Create a new optimization
Parameters: runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
name : string, optional
The name of the optimization.
Returns: id : integer
The optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
report_link : string
A link to the visual report for the optimization.
spot_order_link : string
A link to the json version of the spot order.
file_links : list
Links to the csv and xml versions of the spot order.
runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
-
post_optimizations_clone(id)¶ Clone an existing optimization
Parameters: id : integer
The optimization ID.
Returns: id : integer
The optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
report_link : string
A link to the visual report for the optimization.
spot_order_link : string
A link to the json version of the spot order.
file_links : list
Links to the csv and xml versions of the spot order.
runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
-
post_optimizations_runs(id)¶ Start a run
Parameters: id : integer
The ID of the optimization.
Returns: id : integer
The ID of the run.
optimization_id : integer
The ID of the optimization.
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_spot_orders(*, body='DEFAULT')¶ Create a spot order
Parameters: body : string, optional
CSV body of a spot order.
Returns: id : integer
The ID for the spot order.
archived : string
The archival status of the requested object(s).
csv_s3_uri : string
S3 URI for the spot order CSV file.
json_s3_uri : string
S3 URI for the spot order JSON file.
xml_archive_s3_uri : string
S3 URI for the spot order XML archive.
last_transform_job_id : integer
ID of the spot order transformation job.
-
put_optimizations_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 optimization ID.
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 the optimization.
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.
spot_order_id : integer
The ID for the spot order produced by the optimization.
archived : string
The archival status of the requested object(s).
report_link : string
A link to the visual report for the optimization.
spot_order_link : string
A link to the json version of the spot order.
file_links : list
Links to the csv and xml versions of the spot order.
runs : list:
The runs of the optimization. - market_id : integer The market ID. - start_date : string/date The start date for the media run. - end_date : string/date The end date for the media run. - syscodes : list The syscodes for the media run. - rate_cards : list The ratecards for the media run. - constraints : list:: The constraints for the media run. - targets : list The targets to constrain. - budget : number/float The maximum budget for these targets. - frequency : integer The maximum frequency for these targets.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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_spot_orders(id, *, body='DEFAULT')¶ Edit the specified spot order
Parameters: id : integer
The ID for the spot order.
body : string, optional
CSV body of a spot order.
Returns: id : integer
The ID for the spot order.
archived : string
The archival status of the requested object(s).
csv_s3_uri : string
S3 URI for the spot order CSV file.
json_s3_uri : string
S3 URI for the spot order JSON file.
xml_archive_s3_uri : string
S3 URI for the spot order XML archive.
last_transform_job_id : integer
ID of the spot order transformation job.
-
put_spot_orders_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 the spot order.
archived : string
The archival status of the requested object(s).
csv_s3_uri : string
S3 URI for the spot order CSV file.
json_s3_uri : string
S3 URI for the spot order JSON file.
xml_archive_s3_uri : string
S3 URI for the spot order XML archive.
last_transform_job_id : integer
ID of the spot order transformation job.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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_kwargs, 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(*[, model_name, training_table_name, ...])List list_builds(id, *[, limit, page_num, order, ...])List builds for the given model list_builds_logs(id, build_id, *[, last_id, ...])Get the logs for a build list_projects(id, *[, hidden])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, *[, table_name, database_id, ...])Update model configuration post(*[, table_name, database_id, ...])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, ...[, ...])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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
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(*, model_name='DEFAULT', training_table_name='DEFAULT', dependent_variable='DEFAULT', author='DEFAULT', status='DEFAULT', hidden='DEFAULT', archived='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List
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’.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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, 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, *, limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ 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_builds_logs(id, build_id, *, last_id='DEFAULT', limit='DEFAULT')¶ Get the logs for a build
Parameters: id : integer
The ID of the model.
build_id : integer
The ID of the build.
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_projects(id, *, hidden='DEFAULT')¶ List the projects a models belongs to
Parameters: id : integer
The ID of the resource.
hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
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, *, table_name='DEFAULT', database_id='DEFAULT', credential_id='DEFAULT', model_name='DEFAULT', description='DEFAULT', interaction_terms='DEFAULT', box_cox_transformation='DEFAULT', model_type_id='DEFAULT', primary_key='DEFAULT', dependent_variable='DEFAULT', dependent_variable_order='DEFAULT', excluded_columns='DEFAULT', limiting_sql='DEFAULT', active_build_id='DEFAULT', cross_validation_parameters='DEFAULT', number_of_folds='DEFAULT', notifications='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', time_zone='DEFAULT')¶ 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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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(*, table_name='DEFAULT', database_id='DEFAULT', credential_id='DEFAULT', model_name='DEFAULT', description='DEFAULT', interaction_terms='DEFAULT', box_cox_transformation='DEFAULT', model_type_id='DEFAULT', primary_key='DEFAULT', dependent_variable='DEFAULT', dependent_variable_order='DEFAULT', excluded_columns='DEFAULT', limiting_sql='DEFAULT', active_build_id='DEFAULT', cross_validation_parameters='DEFAULT', number_of_folds='DEFAULT', notifications='DEFAULT', schedule='DEFAULT', parent_id='DEFAULT', time_zone='DEFAULT', hidden='DEFAULT')¶ 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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
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. - success_email_from_name : string Name from which success emails are sent; defaults to "Civis." - success_email_reply_to : string Address for replies to success emails; defaults to the author of the job. - 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.
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, *, limiting_sql='DEFAULT', output_table='DEFAULT', schedule='DEFAULT')¶ 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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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”
share_email_body : string, optional
Custom body text for e-mail sent on a share.
send_shared_email : boolean, optional
Send email to the recipients of a share.
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.
-
Notebooks¶
-
class
Notebooks(session_kwargs, return_type='civis')¶ Methods
delete_deployments(notebook_id, deployment_id)Delete a Notebook deployment delete_projects(id, project_id)Remove a Notebook 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 a Notebook get_deployments(notebook_id, deployment_id)Get details about a Notebook deployment list(*[, hidden, archived, author, status, ...])List Notebooks list_deployments(notebook_id, *[, ...])List deployments for a Notebook list_projects(id, *[, hidden])List the projects a Notebook belongs to list_shares(id)List users and groups permissioned on this object list_update_links(id)Get URLs to update notebook patch(id, *[, name, language, description, ...])Update some attributes of this Notebook post(*[, name, language, description, ...])Create a Notebook post_clone(id)Clone this notebook post_deployments(notebook_id, *[, ...])Deploy a Notebook put(id, *[, name, language, description, ...])Replace all attributes of this Notebook put_archive(id, status)Update the archive status of this object put_projects(id, project_id)Add a Notebook to a project put_shares_groups(id, group_ids, ...[, ...])Set the permissions groups has on this object put_shares_users(id, user_ids, ...[, ...])Set the permissions users have on this object -
delete_deployments(notebook_id, deployment_id)¶ Delete a Notebook deployment
Parameters: notebook_id : integer
The ID of the owning Notebook
deployment_id : integer
The ID for this deployment
Returns: None
Response code 204: success
-
delete_projects(id, project_id)¶ Remove a Notebook 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 a Notebook
Parameters: id : integer
Returns: id : integer
The ID for this notebook.
name : string
The name of this notebook.
language : string
The kernel language of this notebook.
description : string
The description of this notebook.
notebook_url : string
Time-limited URL to get the .ipynb file for this notebook.
notebook_preview_url : string
Time-limited URL to get the .htm preview file for this notebook.
requirements_url : string
Time-limited URL to get the requirements.txt file for this notebook.
file_id : string
The file ID for the S3 file containing the .ipynb file.
requirements_file_id : string
The file ID for the S3 file containing the requirements.txt file.
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.
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).
memory : integer
The amount of memory allocated to the notebook.
cpu : integer
The amount of cpu allocated to the the notebook.
created_at : string/time
updated_at : string/time
most_recent_deployment : dict:
- deployment_id : integer The ID for this deployment. - user_id : integer The ID of the owner. - host : string Domain of the deployment. - name : string Name of the deployment. - 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). - display_url : string URL that displays the deployed platform object and includes auth token. - memory : integer The memory allocated to the deployment. - cpu : integer The cpu allocated to the deployment. - state : string The state of the deployment. - state_message : string A detailed description of the state. - created_at : string/time - updated_at : string/time - published : boolean - notebook_id : integer The ID of owning Notebook
credentials : list
A list of credential IDs to pass to the notebook.
git_url : string
The URL of the repository that will be cloned.
git_branch : string
The name of the branch that will be cloned.
git_file : string
The name of the notebook file within a repository that will be included in the deployment.
environment_variables : dict
Environment variables to be passed into the Notebook.
idle_timeout : integer
How long the notebook will stay alive without any kernel activity.
archived : string
The archival status of the requested object(s).
hidden : boolean
The hidden status of the object.
-
get_deployments(notebook_id, deployment_id)¶ Get details about a Notebook deployment
Parameters: notebook_id : integer
The ID of the owning Notebook
deployment_id : integer
The ID for this deployment
Returns: deployment_id : integer
The ID for this deployment.
user_id : integer
The ID of the owner.
host : string
Domain of the deployment.
name : string
Name of the deployment.
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).
display_url : string
URL that displays the deployed platform object and includes auth token.
memory : integer
The memory allocated to the deployment.
cpu : integer
The cpu allocated to the deployment.
state : string
The state of the deployment.
state_message : string
A detailed description of the state.
created_at : string/time
updated_at : string/time
published : boolean
notebook_id : integer
The ID of owning Notebook
-
list(*, hidden='DEFAULT', archived='DEFAULT', author='DEFAULT', status='DEFAULT', limit='DEFAULT', page_num='DEFAULT', order='DEFAULT', order_dir='DEFAULT', iterator='DEFAULT')¶ List Notebooks
Parameters: hidden : boolean, optional
If specified to be true, returns hidden objects. Defaults to false, returning non-hidden objects.
archived : string, optional
The archival status of the requested object(s).
author : string, optional
If specified, return imports from this author. It accepts a comma-separated list of author IDs.
status : string, optional
If specified, returns notebooks with one of these statuses. It accepts a comma-separated list, possible values are ‘running’, ‘pending’, ‘idle’.
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 for this notebook.
name : string
The name of this notebook.
language : string
The kernel language of this notebook.
description : string
The description of this notebook.
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
most_recent_deployment : dict:
- deployment_id : integer The ID for this deployment. - user_id : integer The ID of the owner. - host : string Domain of the deployment. - name : string Name of the deployment. - docker_image_name : string The name of the docker image to pull from DockerHub. - docker_im
-